ESL

Conectar ESL à operação da sua empresa. Confira os campos necessários, a obtenção das credenciais e o funcionamento na Zild.

Conectar ESL à operação da sua empresa.

Onde configurar

Abra Zild Admin → Integrações → Conectores, localize o provedor e use Configurar ou Editar. Informe os dados deste guia, habilite o conector para o fluxo e salve.

Credenciais da sua empresa

O cliente deve obter e configurar suas próprias chaves de API ou a forma de autenticação exigida por este conector. A assinatura Zild é definida pelo tamanho da empresa; o consumo dos serviços externos é cobrado pelo respectivo provedor, separado da assinatura. Não é necessário configurar conectores que sua operação não utiliza.

Campos necessários

Os requisitos abaixo são os dados necessários ao fluxo que utiliza o conector. O cadastro genérico pode aceitar campos vazios que serão exigidos somente ao executar uma operação. O botão Salvar não confirma que a credencial funciona no provedor.

Como obter as credenciais

1. Solicite ao administrador da sua conta ESL o token API para Data Export e a URL do ambiente.
2. Para operações de ocorrências, solicite também o token usuário com as permissões necessárias.
3. Configure ApiKey e ApiSecret conforme os nomes acima. O caminho exato de emissão depende do ambiente; confirme com o suporte ESL.

Como funciona na Zild

Os tokens têm funções diferentes; solicite somente os necessários à operação.

Como conferir a configuração

Depois de salvar, use o fluxo correspondente (consulta, agente, chamada ou processamento) para verificar o acesso. Se houver erro, confira credencial, permissões e recurso escolhido no provedor. Para tipos limitados ou legados, confirme a disponibilidade com a administração antes de tentar usar.

Na edição, a Zild mostra credenciais protegidas como asteriscos. Preserve o valor mascarado para manter a credencial atual ou cole uma nova credencial para substituí-la.

Documentação oficial

• ESL: suporte / support

Voltar a Conectores

Primeira consulta para a torre de controle

1. Confirme com o administrador ESL o ambiente e o token de Data Export. Configure esse token em ApiKey; o token de usuário para ocorrências pertence a ApiSecret.
2. Habilite somente as ferramentas necessárias ao piloto. Execute esl_list_reports para descobrir os templates disponíveis. Os IDs variam entre ambientes.
3. Use esl_get_report_info com o templateId retornado. Confira os nomes de tabela e campo e os filtros aceitos antes de montar a consulta.
4. Execute esl_get_report_data com um intervalo de data pequeno, page=1 e per=100. A ferramenta aceita até 1000 linhas por página; avance a paginação para conferir o conjunto completo.
5. Compare uma amostra com o ESL: identificador, horário do evento, status e quantidade. Registre quando a consulta foi feita e a cobertura dos filtros para não apresentar dados antigos como posição atual.

O contrato da ferramenta orienta períodos de até 31 dias. Comece com um dia e amplie conforme o volume e os limites do ambiente. A frequência das consultas deve respeitar o provedor; salvar o conector não configura atualização contínua.

Prepare o filtro antes de consultar: search precisa ser um objeto não vazio com o filtro exigido pelo template. Não reutilize nomes de campo de outro relatório sem conferir sua estrutura. Exemplo ilustrativo, válido somente se o template aceitar freights.service_at:

{"search":{"freights":{"service_at":"2026-10-01 - 2026-10-07"}},"page":1,"per":100}

Preserve o mesmo filtro ao avançar as páginas e registre quais foram consultadas. Uma página isolada não comprova o total do relatório. Se o ESL recusar a consulta, confira o campo, o intervalo e a mensagem retornada antes de repetir; uma resposta vazia e uma consulta com erro são situações diferentes.

Ocorrências e cubagem: valide antes de gravar

esl_create_freight_occurrence exige token de usuário, ID interno do frete e código de ocorrência confirmado pela operação. O ID do frete não é o número da minuta. A ocorrência se aplica a todas as notas fiscais do frete; não deduza seu código pelo texto livre. Valide primeiro em homologação, com aprovação do responsável.

esl_update_pick usa número da coleta e data de solicitação. Acrescenta observações e permite registrar cubagem nas condições suportadas, sem alterar status. A integração recusa nova cubagem quando ela já existe e exige revisão da equipe quando há múltiplos itens. O ESL calcula os valores derivados; essa operação não confirma entrega.

Para um piloto de leitura, deixe as ferramentas de escrita desabilitadas. Depois, libere cada ação com seus critérios de identificação, aprovação e conferência no sistema de origem.

Avalie o piloto com casos verificáveis

Baixar planilha de avaliação logística (CSV)

A planilha contém dez cenários sintéticos, todos marcados NOT_RUN. Prepare as entradas em homologação e aprove os critérios com a operação antes de executar. Os casos incluem paginação incompleta, posição atrasada, evento duplicado, evento fora de ordem, identificação do frete, código de ocorrência, cubagem existente, acesso entre clientes e falha do provedor.

ACCEPT significa que o cenário pode seguir o tratamento previsto; não autoriza uma gravação. REVIEW exige revisão ou bloqueio antes de prosseguir. Esses são critérios para configurar e avaliar seu fluxo, não uma afirmação de que o conector sozinho implementa deduplicação, controle de acesso por cliente ou todos os tratamentos descritos.

1. Registre a versão do fluxo, modelo, filtros, permissões e limiar de atualização na evidência da execução. Os 15 minutos do exemplo são uma premissa sintética, não SLA da Zild ou do ESL.
2. Execute cada caso, registre o comportamento observado e marque PASS somente se o critério inteiro foi atendido. Falhas e revisões corretas também precisam de evidência.
3. Compare casos aprovados com casos executados; conte pendências NOT_RUN separadamente. Uma amostra pequena não comprova precisão em produção.
4. Para custo por caso aprovado, some o custo de todas as tentativas, inclusive falhas e repetições, e divida pelos casos aprovados. Use uma moeda única; se nenhum caso passar, o indicador não é calculável.

Exposição entre clientes ou ação duplicada bloqueiam a expansão do piloto até correção e nova avaliação. Defina os demais limites com o responsável operacional.

Selecione ferramentas para o objetivo do piloto

Para começar uma torre de controle de consulta, selecione as operações de listar relatórios, ler a estrutura e consultar dados. Cadastre a ferramenta com um conector ESL habilitado e confirme seu ambiente. Se o seletor estiver vazio, confira o tipo e a habilitação do conector, além de eventuais erros de carregamento; salvar outra ferramenta não corrige a conexão.

Registrar ocorrência de frete e atualizar dados de coleta são operações de escrita e devem ter uma etapa própria de homologação. A configuração atual separa essas ações das consultas. Não use instruções antigas de “adicionar todas” ou de exportação como prova das opções disponíveis na versão do editor em uso; confira o catálogo exibido e as operações necessárias.

Registre o horário real do evento: occurrenceAt aceita data e hora em ISO 8601. Informe o fuso explicitamente, por exemplo 2026-10-07T14:30:00-03:00. Quando esse argumento é omitido, o executor usa o momento atual da execução. Para uma entrega informada com atraso, não omita o horário: isso poderia registrar o momento da integração em vez do momento ocorrido. Confirme o horário com a operação e confira o resultado no ESL.