Entregui para integradores

Documentacao da API v2 para clientes

Guia tecnico para plataformas externas criarem pedidos, consultarem dados de confirmacao e registrarem confirmacao de entrega no Entregui.

Base de producao https://app.entregui.com.br
Formato JSON
Status inicial PENDING
Origem registrada API_KEY

Autenticacao

A API v2 usa uma chave de plataforma vinculada a uma empresa no Entregui. A chave precisa estar ativa, nao excluida e dentro da validade.

Envie a chave em um dos formatos abaixo:

X-API-Key: SUA_CHAVE_DE_API

# Alternativas aceitas:
Authorization: Bearer SUA_CHAVE_DE_API
Authorization: ApiKey SUA_CHAVE_DE_API
Nao exponha a chave em aplicativos frontend, paginas publicas ou apps distribuidos ao usuario final. O envio deve acontecer a partir do backend do cliente ou de um ambiente controlado.

Endpoints disponiveis na API v2

POST /api/v2/orders Cria um pedido pendente para roteirizacao.
GET /api/v2/orders/fetch_order_data?token=TOKEN_DO_PEDIDO Busca dados basicos do cliente para telas externas de confirmacao.
POST /api/v2/orders/confirm_delivery Confirma uma entrega pelo token publico do pedido.

Rotas operacionais

GET /api/v2/orders Lista pedidos enviados pelo cliente com filtros por data, status e custom_id.
GET /api/v2/orders/:id Consulta um pedido especifico e seu status operacional.
GET /api/v2/orders/by_custom_id/:custom_id Consulta um pedido pelo identificador externo do cliente.
GET /api/v2/orders/:id/status Retorna uma visao enxuta do status atual do pedido.
PATCH /api/v2/orders/:id Atualiza dados de um pedido enquanto ele ainda puder ser alterado.
PATCH /api/v2/orders/:id/reschedule Reagenda a data prevista de entrega.
POST /api/v2/orders/:id/hold Coloca o pedido em pendencia operacional.
POST /api/v2/orders/:id/release Libera um pedido pendente para roteirizacao novamente.
DELETE /api/v2/orders/:id Cancela um pedido antes de ele entrar em rota.
POST /api/v2/orders/:id/cancel Cancela um pedido informando motivo e origem da solicitacao.
GET /api/v2/orders/:id/tracking Retorna tracking, rota, motorista e previsao de chegada quando disponivel.
GET /api/v2/orders/:id/events Retorna a linha do tempo do pedido.
GET /api/v2/orders/:id/occurrences Lista ocorrencias, falhas, motivos e observacoes do pedido.
GET /api/v2/webhooks Lista webhooks configurados para a empresa.
POST /api/v2/webhooks Cadastra URL para receber eventos de pedidos.

Rotas de evidencias

GET /api/v2/orders/:id/delivery_evidence Consulta evidencias de entrega pelo ID interno do pedido.
GET /api/v2/orders/delivery_evidence?custom_id=PED-100045 Consulta evidencias usando o identificador externo enviado pelo cliente.
GET /api/v2/orders/:id/delivery_evidence.pdf Baixa um comprovante consolidado em PDF.
GET /api/v2/orders/:id/files Lista anexos, fotos, assinatura e comprovantes vinculados ao pedido.

Rotas e planejamento

GET /api/v2/route_plans/:id Consulta o resultado de um planejamento de rotas.
GET /api/v2/routes/:id/orders Lista os pedidos de uma rota.
GET /api/v2/routes/:id/stops Lista paradas da rota com sequencia, status e pedidos.
GET /api/v2/routes/:id/tracking Acompanha a rota inteira com progresso e posicao operacional.

Cadastros auxiliares

GET /api/v2/warehouses Lista bases disponiveis para uso no warehouse_id.
GET /api/v2/third_parties Lista terceiros vinculados a empresa.
GET /api/v2/enums Retorna valores aceitos para status, flow, confirmation_type, package_size e package_type.

Criar pedido

Cria um pedido com status PENDING, pronto para entrar no planejamento e roteirizacao do Entregui.

POST https://app.entregui.com.br/api/v2/orders

Exemplo com cURL

curl -X POST "https://app.entregui.com.br/api/v2/orders" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -d '{
    "order": {
      "warehouse_id": 1,
      "custom_id": "PED-100045",
      "customer_name": "Joao da Silva",
      "customer_phone": "11999999999",
      "customer_email": "joao@email.com",
      "customer_federal_tax_id": "12345678909",
      "zip": "01311000",
      "address": "Avenida Paulista",
      "number": "1000",
      "complement": "Apto 101",
      "neighborhood": "Bela Vista",
      "city": "Sao Paulo",
      "state": "SP",
      "country": "Brasil",
      "scheduled_dt": "2026-06-16",
      "flow": "DELIVERY",
      "confirmation_type": "PHOTO",
      "package_size": "MEDIUM",
      "package_type": "BOX",
      "weight": 2.5,
      "volume": 0.03,
      "priority": false,
      "note": "Entregar na portaria"
    }
  }'

Exemplo de resposta 201

{
  "message": "Pedido criado com sucesso",
  "order": {
    "id": 123,
    "custom_id": "PED-100045",
    "status": "PENDING",
    "source": "API_KEY",
    "warehouse_id": 1,
    "customer_name": "Joao da Silva",
    "address": "Avenida Paulista",
    "number": "1000",
    "zip": "01311000",
    "city": "Sao Paulo",
    "state": "SP",
    "country": "Brasil",
    "scheduled_dt": "2026-06-16",
    "created_at": "2026-06-15T10:30:00.000-03:00"
  }
}

Campos aceitos ao criar pedido

Campo Obrigatorio Descricao
warehouse_id Opcional ID da base de origem. Se omitido, o Entregui tenta usar o warehouse padrao da empresa. Se nao existir base padrao, a criacao falha.
third_party_id Opcional ID do terceiro vinculado ao pedido. Precisa pertencer a empresa da chave de API.
custom_id Recomendado Identificador do pedido no sistema externo. Use para conciliacao, auditoria e suporte.
customer_name Opcional Nome do destinatario ou cliente.
customer_phone Opcional Telefone do destinatario, preferencialmente com DDD.
customer_email Opcional E-mail do destinatario.
customer_federal_tax_id Opcional CPF ou CNPJ. Quando enviado, precisa ser valido.
zip Obrigatorio CEP do destino. Tambem pode ser usado para enriquecer logradouro, bairro, cidade, UF e pais quando esses campos vierem ausentes.
address Obrigatorio Logradouro. Pode ser preenchido automaticamente via CEP quando o lookup encontrar o endereco.
number Obrigatorio Numero do endereco. Se vier vazio, o backend assume S/N.
complement Opcional Complemento do endereco.
neighborhood Opcional Bairro. Pode ser enriquecido pelo CEP.
city, state, country Opcional Cidade, UF e pais. Podem ser enriquecidos pelo CEP quando ausentes.
city_id, state_id, country_id Opcional IDs internos de localizacao. Quando enviados, o Entregui tambem tenta preencher os nomes correspondentes.
latitude, longitude Opcional Coordenadas do destino. Se nao forem enviadas, o Entregui tenta geocodificar usando o endereco completo.
scheduled_dt Opcional Data prevista de entrega, preferencialmente no formato YYYY-MM-DD.
weight, volume Opcional Peso em kg e volume em m3. O peso maximo aceito e 99999 kg; o volume maximo aceito e 120 m3.
package_size Opcional Valores aceitos: SMALL, MEDIUM, LARGE, NONE.
package_type Opcional Valores aceitos: BOX, BAG, LETTER, NONE.
vehicle_zone Opcional Valores aceitos: FRONT, MIDDLE, BACK, NONE.
vehicle_position Opcional Valores aceitos: FLOOR, SHELF, NONE.
flow Opcional Valores aceitos: DELIVERY, PICKUP, RETURN, EXCHANGE.
confirmation_type Opcional Valores aceitos na API/modelo: PHOTO, SIGNATURE, NONE. O modelo tambem possui WORD, mas confirme o uso antes de integrar.
priority Opcional Booleano para marcar pedido prioritario.
note Opcional Observacao operacional para roteirizacao e entrega.
delivered_at Opcional Campo aceito no payload, mas pedidos criados pela API entram como PENDING. Use apenas quando combinado com o Entregui.

Buscar dados do pedido para confirmacao

Retorna dados basicos do destinatario pelo token publico do pedido. Esse endpoint e usado por fluxos externos de confirmacao.

GET /api/v2/orders/fetch_order_data?token=TOKEN_DO_PEDIDO 
curl -X GET "https://app.entregui.com.br/api/v2/orders/fetch_order_data?token=TOKEN_DO_PEDIDO" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -H "Accept: application/json"

Resposta 200

{
  "customer_federal_tax_id": "12345678909",
  "customer_name": "Joao da Silva",
  "customer_email": "joao@email.com"
}

Respostas especiais

Status Quando acontece
404 Token do pedido nao encontrado para a empresa da chave utilizada.
409 Pedido ja confirmado, ja entregue ou com documento do recebedor preenchido.

Confirmar entrega

Marca o pedido como DELIVERED, grava dados do recebedor, evidencias e coordenadas recebidas. Apos confirmar, usuarios internos da empresa sao notificados.

POST /api/v2/orders/confirm_delivery 
curl -X POST "https://app.entregui.com.br/api/v2/orders/confirm_delivery" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -d '{
    "order": "TOKEN_DO_PEDIDO",
    "recipient_name": "Maria Souza",
    "recipient_document_type": "CPF",
    "recipient_document_number": "12345678909",
    "evidence": "BASE64_OU_REFERENCIA_DA_EVIDENCIA",
    "signature": "BASE64_OU_REFERENCIA_DA_ASSINATURA",
    "received_latitude": "-23.561684",
    "received_longitude": "-46.655981"
  }'

Em caso de sucesso, a API retorna 200 OK sem corpo.

Campo Descricao
order Token publico do pedido. E obrigatorio para localizar a entrega.
recipient_name Nome de quem recebeu.
recipient_document_type Tipo do documento informado, por exemplo CPF ou RG.
recipient_document_number Numero do documento do recebedor.
evidence Evidencia da entrega quando o fluxo exigir foto ou comprovante.
signature Assinatura quando o fluxo exigir assinatura.
received_latitude, received_longitude Coordenadas de onde a confirmacao foi realizada.

Rotas operacionais da API

Listar pedidos

GET https://app.entregui.com.br/api/v2/orders 
curl -X GET "https://app.entregui.com.br/api/v2/orders?status=DELIVERED&scheduled_from=2026-06-01&scheduled_to=2026-06-30&page=1&per_page=50" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -H "Accept: application/json"
{
  "orders": [
    {
      "id": 123,
      "custom_id": "PED-100045",
      "status": "DELIVERED",
      "warehouse_id": 1,
      "customer_name": "Joao da Silva",
      "scheduled_dt": "2026-06-16",
      "delivered_at": "2026-06-16T17:20:00.000-03:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 1
  }
}
Filtro Uso
status Filtrar por PENDING, ROUTED, IN_ROUTE, DELIVERED, FAILED, CANCELED.
custom_id Encontrar pedido pelo identificador enviado pelo cliente.
scheduled_from, scheduled_to Filtrar por janela de data prevista de entrega.
updated_since Sincronizar somente pedidos alterados apos uma data/hora.
page, per_page Paginar resultados para integracoes com alto volume.

Consultar pedido

GET https://app.entregui.com.br/api/v2/orders/:id 
curl -X GET "https://app.entregui.com.br/api/v2/orders/123" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -H "Accept: application/json"

Alternativa: GET /api/v2/orders/by_custom_id/PED-100045, para clientes que nao armazenam o ID interno do Entregui. 

curl -X GET "https://app.entregui.com.br/api/v2/orders/by_custom_id/PED-100045" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -H "Accept: application/json"

Status do pedido

GET https://app.entregui.com.br/api/v2/orders/:id/status 
{
  "id": 123,
  "custom_id": "PED-100045",
  "status": "IN_ROUTE",
  "status_label": "Em rota",
  "updated_at": "2026-06-17T14:10:00.000-03:00"
}

Atualizar pedido

PATCH https://app.entregui.com.br/api/v2/orders/:id 
curl -X PATCH "https://app.entregui.com.br/api/v2/orders/123" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -d '{
    "order": {
      "scheduled_dt": "2026-06-18",
      "customer_phone": "11988887777",
      "note": "Cliente solicitou entrega no periodo da tarde"
    }
  }'
Regra: permitir alteracao somente enquanto o pedido estiver em status editavel, por exemplo PENDING ou ON_HOLD. Pedidos ja roteirizados ou em rota devem exigir fluxo especifico de replanejamento.

Reagendar pedido

PATCH https://app.entregui.com.br/api/v2/orders/:id/reschedule 
curl -X PATCH "https://app.entregui.com.br/api/v2/orders/123/reschedule" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -d '{
    "scheduled_dt": "2026-06-19",
    "reason": "Cliente solicitou nova data"
  }'

Colocar pedido em pendencia

POST https://app.entregui.com.br/api/v2/orders/:id/hold 
curl -X POST "https://app.entregui.com.br/api/v2/orders/123/hold" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -d '{
    "reason": "Endereco incompleto",
    "note": "Aguardando complemento do cliente"
  }'

Liberar pedido pendente

POST https://app.entregui.com.br/api/v2/orders/:id/release 
curl -X POST "https://app.entregui.com.br/api/v2/orders/123/release" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -d '{
    "note": "Endereco revisado e liberado para roteirizacao"
  }'

Cancelar pedido

DELETE https://app.entregui.com.br/api/v2/orders/:id 
curl -X DELETE "https://app.entregui.com.br/api/v2/orders/123" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -d '{
    "reason": "Cliente cancelou a compra"
  }'
Regra: cancelar apenas pedidos que ainda nao estejam entregues. Caso ja exista rota, a API deve registrar auditoria e orientar se a parada sera removida, ignorada ou tratada manualmente.

Alternativa equivalente para clientes que preferem verbo de acao: POST /api/v2/orders/:id/cancel.

Tracking do pedido

GET https://app.entregui.com.br/api/v2/orders/:id/tracking 
{
  "order": {
    "id": 123,
    "custom_id": "PED-100045",
    "status": "IN_ROUTE"
  },
  "tracking": {
    "tracking_url": "https://delivery.entregui.com.br/f/TOKEN",
    "eta": "2026-06-17T16:30:00.000-03:00",
    "last_event": "Motorista saiu para entrega",
    "driver_name": "Rafael Gmail",
    "vehicle_name": "Van 01"
  }
}

Linha do tempo do pedido

GET https://app.entregui.com.br/api/v2/orders/:id/events 
{
  "events": [
    {
      "type": "order.created",
      "description": "Pedido criado via API",
      "occurred_at": "2026-06-17T09:10:00.000-03:00"
    },
    {
      "type": "order.routed",
      "description": "Pedido roteirizado",
      "occurred_at": "2026-06-17T10:05:00.000-03:00"
    },
    {
      "type": "order.delivered",
      "description": "Pedido entregue",
      "occurred_at": "2026-06-17T15:40:00.000-03:00"
    }
  ]
}

Ocorrencias do pedido

GET https://app.entregui.com.br/api/v2/orders/:id/occurrences 
{
  "occurrences": [
    {
      "type": "DELIVERY_FAILED",
      "reason": "Cliente ausente",
      "note": "Portaria informou que nao havia ninguem para receber",
      "occurred_at": "2026-06-17T15:05:00.000-03:00",
      "latitude": "-23.561684",
      "longitude": "-46.655981"
    }
  ]
}

Webhooks

GET /api/v2/webhooks Lista endpoints cadastrados.
POST /api/v2/webhooks Cria endpoint de webhook.
DELETE /api/v2/webhooks/:id Remove endpoint de webhook. 
curl -X POST "https://app.entregui.com.br/api/v2/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -d '{
    "webhook": {
      "url": "https://cliente.com.br/webhooks/entregui",
      "events": [
        "order.routed",
        "order.in_route",
        "order.delivered",
        "order.delivery_failed",
        "order.canceled",
        "order.rescheduled",
        "order.on_hold",
        "delivery_evidence.created"
      ]
    }
  }'
Evento Quando enviar
order.created Pedido criado com sucesso no Entregui.
order.routed Pedido entrou em uma rota.
order.in_route Motorista iniciou rota ou pedido saiu para entrega.
order.delivered Pedido entregue com sucesso.
order.delivery_failed Entrega marcada como falha.
order.canceled Pedido cancelado no Entregui.
order.rescheduled Pedido reagendado para nova data.
order.on_hold Pedido colocado em pendencia operacional.
delivery_evidence.created Comprovante, foto ou assinatura de entrega disponibilizado.

Evidencias de entrega

Consultar evidencias por ID interno

GET https://app.entregui.com.br/api/v2/orders/:id/delivery_evidence 
curl -X GET "https://app.entregui.com.br/api/v2/orders/123/delivery_evidence" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -H "Accept: application/json"

Consultar evidencias por custom_id

GET https://app.entregui.com.br/api/v2/orders/delivery_evidence?custom_id=PED-100045 
curl -X GET "https://app.entregui.com.br/api/v2/orders/delivery_evidence?custom_id=PED-100045" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -H "Accept: application/json"

Baixar comprovante em PDF

GET https://app.entregui.com.br/api/v2/orders/:id/delivery_evidence.pdf 
curl -X GET "https://app.entregui.com.br/api/v2/orders/123/delivery_evidence.pdf" \
  -H "X-API-Key: SUA_CHAVE_DE_API" \
  -H "Accept: application/pdf" \
  --output comprovante-entrega-123.pdf

Listar arquivos e anexos

GET https://app.entregui.com.br/api/v2/orders/:id/files 
{
  "files": [
    {
      "type": "evidence",
      "filename": "foto-entrega.jpg",
      "content_type": "image/jpeg",
      "url": "https://app.entregui.com.br/rails/active_storage/..."
    },
    {
      "type": "signature",
      "filename": "assinatura.png",
      "content_type": "image/png",
      "url": "https://app.entregui.com.br/rails/active_storage/..."
    }
  ]
}

Resposta JSON

{
  "order": {
    "id": 123,
    "custom_id": "PED-100045",
    "status": "DELIVERED",
    "delivered_at": "2026-06-17T15:40:00.000-03:00",
    "warehouse_id": 1
  },
  "recipient": {
    "name": "Maria Souza",
    "document_type": "CPF",
    "document_number": "12345678909"
  },
  "location": {
    "received_latitude": "-23.561684",
    "received_longitude": "-46.655981"
  },
  "evidence": {
    "confirmation_type": "PHOTO",
    "evidence_url": "https://app.entregui.com.br/rails/active_storage/...",
    "signature_url": null,
    "pod_pdf_url": "https://app.entregui.com.br/api/v2/orders/123/delivery_evidence.pdf"
  }
}

Regras

Regra Descricao
Autenticacao Deve usar a mesma chave de API v2. A evidencia so pode ser consultada se o pedido pertencer a empresa da chave.
Identificador recomendado Para clientes externos, a consulta por custom_id tende a ser a mais simples, pois usa o identificador original enviado na criacao do pedido.
Pedido ainda nao entregue A API retorna erro controlado quando o pedido ainda nao esta com status DELIVERED.
Evidencia ausente Quando a entrega nao tiver foto ou assinatura, a resposta deve retornar os campos como null, mantendo os dados do recebedor quando existirem.
URLs de arquivos As URLs retornadas devem ser temporarias ou protegidas, evitando exposicao publica permanente de documentos e fotos.

Erros

Status Quando acontece
401 Chave ausente, invalida, expirada ou sem acesso a empresa do pedido.
404 Pedido nao encontrado pelo id ou custom_id informado.
409 Pedido encontrado, mas ainda nao esta entregue.

Rotas e planejamento

Endpoints para clientes que precisam acompanhar o agrupamento dos pedidos em rotas, paradas, sequencia operacional e progresso da entrega.

Consultar planejamento

GET https://app.entregui.com.br/api/v2/route_plans/:id 
{
  "route_plan": {
    "id": 55,
    "scheduled_date": "2026-06-17",
    "status": "approved",
    "warehouse_id": 1,
    "total_routes": 4,
    "total_assigned_orders": 120,
    "total_unassigned_orders": 3
  }
}

Pedidos da rota

GET https://app.entregui.com.br/api/v2/routes/:id/orders 
{
  "route": {
    "id": 88,
    "status": "IN_ROUTE",
    "driver_name": "Rafael Gmail",
    "vehicle_name": "Van 01"
  },
  "orders": [
    {
      "id": 123,
      "custom_id": "PED-100045",
      "status": "IN_ROUTE",
      "stop_order": 1
    }
  ]
}

Paradas da rota

GET https://app.entregui.com.br/api/v2/routes/:id/stops 
{
  "stops": [
    {
      "id": 701,
      "stop_order": 1,
      "status": "COMPLETED",
      "address": "Avenida Paulista, 1000",
      "orders_count": 2,
      "completed_at": "2026-06-17T15:40:00.000-03:00"
    }
  ]
}

Tracking da rota

GET https://app.entregui.com.br/api/v2/routes/:id/tracking 
{
  "route": {
    "id": 88,
    "status": "IN_ROUTE",
    "progress": {
      "completed_stops": 6,
      "total_stops": 12,
      "completed_orders": 14,
      "total_orders": 28
    },
    "vehicle": {
      "name": "Van 01",
      "last_latitude": "-23.561684",
      "last_longitude": "-46.655981"
    }
  }
}

Cadastros auxiliares

Endpoints de apoio para descobrir IDs e valores aceitos antes de criar pedidos.

Bases/warehouses

GET https://app.entregui.com.br/api/v2/warehouses 
{
  "warehouses": [
    {
      "id": 1,
      "name": "Base Sao Paulo",
      "default": true,
      "city": "Sao Paulo",
      "state": "SP"
    }
  ]
}

Terceiros

GET https://app.entregui.com.br/api/v2/third_parties 
{
  "third_parties": [
    {
      "id": 10,
      "name": "Transportadora Parceira",
      "document": "12345678000190"
    }
  ]
}

Enums e valores aceitos

GET https://app.entregui.com.br/api/v2/enums 
{
  "order_statuses": ["PENDING", "ON_HOLD", "ROUTED", "IN_ROUTE", "DELIVERED", "FAILED", "CANCELED"],
  "flows": ["DELIVERY", "PICKUP", "RETURN", "EXCHANGE"],
  "confirmation_types": ["PHOTO", "SIGNATURE", "NONE"],
  "package_sizes": ["SMALL", "MEDIUM", "LARGE", "NONE"],
  "package_types": ["BOX", "BAG", "LETTER", "NONE"]
}

Erros comuns

Status Mensagem comum Causa provavel
401 Unauthorized Chave ausente, invalida, expirada, excluida ou sem empresa vinculada.
401 Token invalido Token publico do pedido nao encontrado no fluxo de confirmacao.
401 Pedido invalido Tentativa de confirmar entrega de pedido ja entregue.
422 warehouse_id invalido para esta empresa. Base informada nao pertence a empresa da chave ou nao existe.
422 third_party_id invalido para esta empresa. Terceiro informado nao pertence a empresa da chave.
422 Lista de validacoes do pedido Campos obrigatorios ausentes, CPF/CNPJ invalido, peso/volume fora do limite ou valor enum invalido.

Boas praticas para integracao

Envio de pedidos

Envie custom_id sempre que possivel para rastreabilidade entre sistemas.

Envie latitude e longitude quando ja possuir coordenadas confiaveis.

Prefira datas em YYYY-MM-DD para scheduled_dt.

Use warehouse_id explicitamente quando a empresa tiver mais de uma base.

Operacao e seguranca

Trate respostas 4xx como falha de validacao/autenticacao e corrija o payload antes de reenviar.

Nao faca retentativas infinitas para erros 401 ou 422.

Armazene a chave de API em variavel de ambiente ou cofre de segredos.

Teste em ambiente combinado com o Entregui antes de ativar a integracao em producao.