# ESL

Connect ESL to your company operations. Review required fields, credential setup and how this connector works in Zild.

Source: https://zild.ai/en-US/docs/apps/zild-admin/connector-esl

Connect ESL to your company operations.

## Where to configure

Open Zild Admin → Integrations → Connectors, find the provider and use Configure or Edit. Enter the data from this guide, enable the connector for the workflow and save.

## Your company credentials

Customers must obtain and configure their own API keys or the authentication method required by this connector. The Zild subscription is based on company size; external service usage is billed separately by the respective provider. You do not need to configure connectors your operation does not use.

## Required fields

These requirements are the data needed by the workflow using the connector. Generic saving may accept empty fields that are only required when an operation runs. Saving does not confirm that the provider accepts the credential.



<table class="api-params"><thead><tr><th>Field</th><th>Workflow requirement</th></tr></thead><tbody><tr><td><code>Url</code></td><td>ESL environment HTTPS base URL, without appending /api/analytics or /api/v1; the integration adds the routes.</td></tr><tr><td><code>ApiKey</code></td><td>API token for Data Export.</td></tr><tr><td><code>ApiSecret</code></td><td>User token for occurrences when required.</td></tr></tbody></table>



## How to obtain credentials

- Ask your ESL account administrator for the Data Export API token and environment URL.
- For occurrence operations, also request a user token with the required permissions.
- Configure ApiKey and ApiSecret as described above. The exact issuance path depends on your environment; confirm with ESL support.

## How it works in Zild

The tokens have different purposes; request only those required for your workflow.

## How to verify the configuration

After saving, use the matching workflow (query, agent, call or processing) to verify access. If it fails, check the credential, permissions and selected provider resource. For limited or legacy types, confirm availability with your administrator before use.

When editing, Zild displays protected credentials as asterisks. Preserve the masked value to keep the current credential or paste a new credential to replace it.

## Official documentation

- [ESL: suporte / support](https://www.esl.com.br/)

[Back to Connectors](/en-US/docs/apps/zild-admin/integration)

## First query for the control tower

- Confirm the environment and Data Export token with the ESL administrator. Set this token in ApiKey; the user token for occurrences belongs in ApiSecret.
- Enable only tools required by the pilot. Run esl_list_reports to discover available templates. IDs vary across environments.
- Use esl_get_report_info with the returned templateId. Check table and field names and accepted filters before building the query.
- Run esl_get_report_data with a small date range, page=1 and per=100. The tool accepts up to 1000 rows per page; paginate to check the complete result set.
- Compare a sample with ESL: identifier, event time, status and quantity. Record query time and filter coverage so stale data is not presented as the current position.

The tool contract recommends periods of up to 31 days. Start with one day and expand according to volume and environment limits. Query frequency must respect provider limits; saving the connector does not configure continuous updates.

**Prepare the filter before querying:** search must be a non-empty object containing the filter required by the template. Do not reuse another report’s field names without checking its structure. Illustrative example, valid only if the template accepts freights.service_at:



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

Keep the same filter while advancing pages and record which pages were queried. A single page does not establish the report total. If ESL rejects the query, check the field, range and returned message before retrying; an empty response differs from a failed query.

## Occurrences and measurements: validate before writing

esl_create_freight_occurrence requires a user token, internal freight ID and an occurrence code confirmed by operations. The freight ID is not the shipment document number. The occurrence applies to every invoice in the freight; do not infer its code from free text. Validate in a test environment first, with the owner's approval.

esl_update_pick uses the pickup number and request date. It appends comments and records measurements under supported conditions, without changing status. The integration rejects new measurements when they already exist and requires team review for multiple items. ESL calculates derived values; this operation does not confirm delivery.

For a read-only pilot, keep write tools disabled. Then enable each action with its identification, approval and source-system verification criteria.

## Evaluate the pilot with verifiable cases

[Download logistics evaluation worksheet (CSV)](/assets/templates/logistics-evaluation-en-US.csv)

The worksheet contains ten synthetic scenarios, all marked NOT_RUN. Prepare test-environment inputs and agree acceptance criteria with operations before running them. Cases cover incomplete pagination, stale positions, duplicate events, out-of-order events, freight identity, occurrence codes, existing measurements, cross-customer access and provider failures.

ACCEPT means the scenario can follow its intended handling; it does not authorize a write. REVIEW requires review or blocking before proceeding. These are criteria for configuring and evaluating your workflow, not a claim that the connector alone implements deduplication, customer-level access controls or every handling rule described.

- Record workflow version, model, filters, permissions and freshness threshold in the run evidence. The example's 15 minutes is a synthetic assumption, not a Zild or ESL SLA.
- Run each case, record observed behavior and mark PASS only when the entire criterion is met. Failures and correct reviews also need evidence.
- Compare passed cases with executed cases; count NOT_RUN cases separately. A small sample does not establish production accuracy.
- For cost per passed case, sum the cost of all attempts, including failures and retries, and divide by passed cases. Use one currency; if no case passes, the metric cannot be calculated.

Cross-customer disclosure or duplicate actions block pilot expansion until corrected and reevaluated. Agree other thresholds with the operational owner.

## Select tools for the pilot objective

To start a query-based control tower, select the operations for listing reports, reading their structure and querying data. Configure the tool with an enabled ESL connector and confirm its environment. If the selector is empty, check connector type and enabled status, as well as loading errors; saving another tool does not repair the connection.

Registering a freight occurrence and updating pickup data are write operations and need their own staging validation. Current configuration separates these actions from queries. Do not treat older “add all” or export instructions as proof of the options available in the editor version being used; check the displayed catalog and the operations required.

**Record the actual event time:** occurrenceAt accepts an ISO 8601 date and time. Include the time-zone offset explicitly, for example 2026-10-07T14:30:00-03:00. When omitted, the executor uses the current execution time. For a delivery reported late, do not omit the timestamp: this could record integration time instead of the event time. Confirm the time with operations and verify the result in ESL.