Entregui para integradores

Changelog

Novidades, melhorias e correções da API Entregui e da documentação, em um só lugar.

Evolução da API pública v2 e da documentação, com os registros mais recentes primeiro. Cada atualização descreve o que mudou e o impacto para sua integração.

Outubro de 2026

Documentação da API em um portal próprio

A documentação para clientes passa a ser mantida no repositório Dev, com um guia dedicado à API v2.

  • Guia de autenticação, criação e confirmação de pedidos, consultas operacionais, evidências, rotas e cadastros auxiliares.
  • Exemplos de requisições e respostas, erros comuns e boas práticas para integradores.
Documentação para consulta A criação do portal não altera endpoints ou contratos da API. Esta página de changelog acrescenta o histórico técnico a esse material.
Consultar documentação relacionada →

Webhooks com mais dados do pedido

Os eventos de pedidos passam a incluir dados adicionais para conciliar a operação com o sistema do integrador.

  • Incluídos value, volume, weight, invoice_number, packages_count, third_party_id e confirmation_type.
  • Também passam a compor o payload vehicle_zone, pickup_at, attention_to, priority, refrigeration, flow e note.
Campos adicionais no JSON Os campos existentes foram preservados. Receptores com validação rígida devem aceitar os novos atributos.
Consultar documentação relacionada →

Nota fiscal e chave de acesso na entrada de pedidos

A criação e a atualização de pedidos passam a aceitar os identificadores fiscais enviados pela integração.

  • Os parâmetros invoice_number e access_key foram incluídos entre os campos permitidos de POST /api/v2/orders e PATCH /api/v2/orders/:id.
Adoção opcional Integrações que já enviavam esses campos passam a ter seus valores aceitos. Os demais campos do pedido mantêm o comportamento anterior.
Consultar documentação relacionada →

Orientações da empresa na consulta de pedidos

O pedido passa a expor o texto de orientação definido pela empresa para o momento da confirmação de entrega.

  • O payload público inclui delivery_confirmation_instructions.
  • A orientação é opcional e não representa uma nova regra de validação da entrega.
Campo opcional A integração pode apresentar o texto quando preenchido e omitir a orientação quando o valor estiver vazio.
Consultar documentação relacionada →

Quantidade mínima de fotos com adoção explícita das regras

A consulta de pedidos informa o mínimo de fotos exigido pela empresa, além do limite máximo já disponível.

  • Adicionado min_delivery_evidence_photos ao payload público.
  • A confirmação aceita evidence_rules_version=1 para indicar que o cliente conhece as regras de quantidade mínima.
Compatibilidade por capacidade do cliente Clientes que adotam evidence_rules_version=1 devem respeitar os limites informados. Clientes sem esse indicador preservam o fluxo legado de envio de uma foto.
Consultar documentação relacionada →

Confirmações seguras para novas tentativas de envio

A confirmação pode reconhecer uma tentativa repetida e recuperar o resultado já registrado.

  • Adicionado o identificador opcional delivery_confirmation_id.
  • O envio de evidências passa por um fluxo centralizado e atômico. Repetições reconhecidas não substituem a confirmação salva nem reenviam suas notificações.
Reutilize a chave na mesma confirmação Mantenha o identificador e os dados ao repetir uma tentativa após falha de comunicação. O identificador continua opcional para o fluxo legado.
Consultar documentação relacionada →

Múltiplas fotos como evidência de entrega

Uma entrega pode receber fotos adicionais e disponibilizar todas as evidências para consulta.

  • A confirmação aceita additional_evidences[] e additional_evidences_metadata, além da foto principal em evidence.
  • A consulta de evidências inclui evidence_urls e evidences, com posição e metadados por captura. O campo legado evidence_url continua apontando para a primeira foto.
  • A listagem de arquivos, os webhooks de evidência e o comprovante em PDF passam a contemplar as fotos adicionais. O pedido informa max_delivery_evidence_photos.
Fluxo legado preservado O envio de uma foto e os campos anteriores continuam disponíveis. Para enviar fotos adicionais, respeite o limite configurado para a empresa.
Consultar documentação relacionada →

Quantidade de volumes recebida pela API

O número de volumes pode acompanhar os dados enviados na criação ou atualização de um pedido.

  • O parâmetro packages_count foi incluído entre os atributos aceitos pela API v2.
Campo adicional Envie a quantidade de volumes quando ela estiver disponível no sistema de origem.
Consultar documentação relacionada →

Setembro de 2026

Indicação de ordem flexível nas rotas

O retorno público de uma rota passa a informar se a operação permite visitar as paradas em ordem flexível.

  • Adicionado o atributo flexible_stop_order ao payload de rota.
Campo adicional na consulta A integração pode usar esse indicador para interpretar a sequência operacional. O campo descreve a configuração da rota e não muda a ordem dos dados por si só.
Consultar documentação relacionada →

Confirmação bloqueada durante transferência entre bases

A API impede registrar uma entrega final enquanto o pedido estiver vinculado a uma rota de transferência ativa.

  • POST /api/v2/orders/confirm_delivery retorna 409 Conflict com a mensagem de que o pedido está em uma rota de transferência.
Trate o conflito operacional Aguarde a resolução da transferência antes de tentar a confirmação de entrega final.
Consultar documentação relacionada →

Tipo de confirmação com foto e assinatura

O tipo PHOTO_SIGNATURE passa a fazer parte das modalidades de confirmação de pedidos.

  • O catálogo de tipos de confirmação inclui PHOTO_SIGNATURE.
  • A validação da entrega combinada exige foto, assinatura, nome e documento do recebedor. Falhas de validação são devolvidas em 422 Unprocessable Entity.
Revise os tipos aceitos pelo seu sistema Para utilizar a modalidade combinada, envie os anexos e os dados exigidos. Os tipos PHOTO, SIGNATURE e NONE permanecem disponíveis.
Consultar documentação relacionada →

Tipo de confirmação padrão aplicado na criação

Pedidos criados sem um tipo de confirmação preenchido passam a utilizar o padrão definido pela empresa.

  • O fallback considera tanto a ausência de confirmation_type quanto o envio de valor vazio.
Confira o padrão da empresa Para definir uma modalidade específica por pedido, envie confirmation_type preenchido.
Consultar documentação relacionada →

Agosto de 2026

Valor do pedido aceito na integração

O valor financeiro do pedido pode ser informado pelo sistema de origem.

  • O atributo value foi adicionado aos parâmetros permitidos na criação e atualização de pedidos.
Adoção opcional O campo é adicional; pedidos sem valor informado continuam seguindo o fluxo de criação.
Consultar documentação relacionada →

Carimbo de data e localização nas fotos

Fotos recebidas na confirmação podem receber a marca d’água configurada pela empresa.

  • Aceitos evidence_taken_at, evidence_latitude e evidence_longitude para identificar a captura.
  • As coordenadas da confirmação também aceitam latitude/longitude e lat/lng, além de received_latitude/received_longitude.
Envie os dados reais da captura O recurso depende da configuração da empresa. A assinatura permanece como anexo separado da foto.
Consultar documentação relacionada →

Cancelamento bloqueado para pedido em rota

O cancelamento pela API passa a proteger pedidos que já estão em execução na rota.

  • As ações de cancelamento retornam 409 Conflict quando o status do pedido é IN_ROUTE.
  • O bloqueio já existente para pedidos DELIVERED foi mantido.
Trate a resposta 409 Não repita o cancelamento sem uma mudança da situação operacional do pedido.
Consultar documentação relacionada →

Junho de 2026

Criação de pedidos vinculada ao responsável da empresa

A criação de pedidos pela API passa a registrar o responsável da empresa e a validar sua existência.

  • O responsável de criação é resolvido pelo proprietário da empresa.
  • Sem proprietário cadastrado, a API retorna 422 com uma mensagem específica.
Cadastro da empresa necessário Se receber essa rejeição, regularize o proprietário da empresa antes de reenviar o pedido.
Consultar documentação relacionada →

Assinatura e identificação padronizadas nos webhooks

Os webhooks passam a identificar o evento e o envio com cabeçalhos próprios da Entregui.

  • Incluídos X-Entregui-Event, X-Entregui-Webhook-Id, X-Entregui-Timestamp, X-Entregui-Signature e, quando disponível, X-Entregui-Delivery-Id.
  • A assinatura usa HMAC-SHA256 do conteúdo timestamp.corpo_original, com o prefixo sha256= no valor do cabeçalho.
  • O cabeçalho legado X-Webhook-Signature foi removido. Os endpoints passam a contar com chave secreta e opção de regeneração.
Atualize a validação do receptor Valide X-Entregui-Signature com a chave do endpoint, o timestamp recebido e os bytes originais do corpo. Receptores que dependiam do cabeçalho legado precisam ser adaptados.
Consultar documentação relacionada →

Eventos operacionais e seleção explícita de webhooks

A integração passa a acompanhar as etapas do pedido e a escolher quais notificações deseja receber.

  • Catálogo com order.created, order.updated, order.routed, order.in_route, order.delivered, order.delivery_failed, order.canceled, order.rescheduled, order.on_hold e delivery_evidence.created.
  • Os payloads podem incluir rota, parada, ocorrência de falha e evidências conforme o evento.
  • O cadastro pela API exige ao menos um evento válido em events; sem seleção válida, retorna 422. O catálogo é consultável em /api/v2/enums.
Selecione os eventos ao cadastrar Envie os eventos desejados no cadastro de cada webhook e prepare o receptor para os payloads correspondentes.
Consultar documentação relacionada →

Identificador externo nos eventos de criação

Os webhooks de criação passam a incluir a referência do pedido no sistema de origem.

  • Adicionado custom_id ao payload de order.created.
Conciliação pelo identificador do cliente Use o custom_id informado na criação para associar o evento ao pedido no seu sistema.
Consultar documentação relacionada →

Consultas e operações públicas da API v2

A API pública é ampliada para acompanhar o pedido desde a criação até a entrega.

  • Listagem e consulta de pedidos por ID ou custom_id, status, filtros e paginação; atualização, reagendamento, pendência, liberação e cancelamento.
  • Consultas de tracking, eventos, ocorrências, arquivos e evidências, incluindo comprovante em PDF.
  • Consultas de planejamento, pedidos e paradas de uma rota, bases, terceiros e enums; cadastro, teste, listagem e exclusão de webhooks.
  • Autorização por chave de plataforma vinculada à empresa e registro da última utilização da chave.
Operações limitadas à empresa da chave Utilize a chave da empresa e consulte as regras de cada ação. A paginação usa 50 itens por padrão e permite até 100 por página.
Consultar documentação relacionada →

Maio de 2026

Primeiros webhooks de pedidos

O backend passa a enviar eventos de pedidos para as URLs configuradas pela empresa.

  • Envio assíncrono de eventos de criação e atualização de status, com gerenciamento das inscrições.
  • Introduzidos o envelope JSON com evento e dados do pedido e a assinatura do conteúdo enviado.
Registro histórico O contrato de eventos e a assinatura foram evoluídos nos registros de junho de 2026. Consulte essas alterações ao implementar um receptor atual.
Consultar documentação relacionada →

Evolução da geocodificação de pedidos

A localização de pedidos sem coordenadas completas passa a utilizar o serviço de geocodificação da plataforma.

  • O preenchimento de latitude e longitude considera o endereço do pedido quando necessário.
  • Coordenadas completas já informadas pela integração são preservadas.
Contrato de entrada preservado Continue enviando endereço e, quando disponíveis, latitude e longitude confiáveis.
Consultar documentação relacionada →

Notificação após confirmação externa de entrega

A confirmação realizada pela integração passa a gerar uma notificação para os usuários elegíveis da empresa.

  • O fluxo de sucesso retorna 200 OK sem corpo.
  • Falhas na geração da notificação são tratadas separadamente da confirmação já registrada.
Resposta de sucesso sem JSON Trate o status HTTP como confirmação de sucesso; não dependa de um corpo JSON nessa operação.
Consultar documentação relacionada →

Consulta dos dados para confirmação externa

Adicionado o endpoint de consulta dos dados básicos do cliente antes da confirmação de entrega.

  • GET /api/v2/orders/fetch_order_data?token=... retorna nome, e-mail e documento do cliente.
  • Token não encontrado retorna 404; pedido já confirmado retorna 409.
Trate pedidos já confirmados Use o token do pedido e a chave da empresa. Em 409, evite solicitar novamente os dados do recebedor.
Consultar documentação relacionada →

Abril de 2026

Confirmação de entrega pela API v2

A integração passa a registrar a entrega por meio do token público do pedido.

  • A confirmação recebe foto, assinatura, dados do recebedor e coordenadas, atualizando o status para DELIVERED.
  • O endpoint valida o token e a situação do pedido antes de registrar a entrega.
Regras evoluídas nos registros seguintes Consulte os registros posteriores sobre anexos, repetição de envio e validações antes de implementar esse fluxo.
Consultar documentação relacionada →

Criação de pedidos no namespace da API v2

A criação de pedidos de integrações passa a contar com um endpoint próprio na API v2.

  • POST /api/v2/orders aceita os dados do cliente, endereço, base, terceiro e informações operacionais.
  • A chave de plataforma é validada por empresa. Pedidos criados entram com status PENDING e origem API_KEY.
  • Incluídas validações de base e terceiro, preenchimento de endereço por CEP e geocodificação quando necessária.
Autenticação e validação do payload Use uma chave válida da empresa e trate 401 para autenticação e 422 para rejeições de validação.
Consultar documentação relacionada →

Como ler este histórico

Novidade Melhoria Correção Documentação

Consulte em cada registro as orientações de compatibilidade e as ações necessárias para sua integração. O histórico da API v2 foi reconstruído desde abril de 2026. Ajustes internos da interface web e funcionalidades exclusivas do App não fazem parte desta página.