Gestão Logística de Entrega

Visão Geral

Este módulo permite que parceiros integradores notifiquem o aiqfome sobre cada etapa do ciclo logístico do pedido. O objetivo é fornecer visibilidade em tempo real para Sellers e Clientes Finais através de rastreamento preciso.

Regras de Negócio e Operação

• Permissão: O integrador ou canal de vendas deve possuir permissão da loja para alterar os status da entrega. Esta permissão é concedida pelo Seller no Painel do Geraldo ao autorizar os escopos de acesso durante o processo de vinculação da aplicação.

• Sequência Lógica: Os status logísticos devem ser atualizados em ordem obrigatória. A API retorna erro se algum status for pulado (por exemplo, ao tentar informar DELIVERY_ONGOING antes do ARRIVED_AT_MERCHANT). A exceção é o status DELIVERY_CANCELED, que pode ser enviado a qualquer momento do ciclo.

• Dados do Entregador: O envio do nome e telefone do entregador é opcional. Caso esses campos sejam omitidos, eles serão registrados como nulos e o status será atualizado normalmente.

• Webhooks: Cada transição de status realizada com sucesso dispara um evento de webhook. O parceiro integrador deve cadastrar esses eventos conforme o fluxo de registro existente. Para mais detalhes, consulte a Documentação de Webhooks.

Entregador a Caminho da Loja

Indica que um entregador foi alocado para o pedido e iniciou o deslocamento até o estabelecimento. Este é o marco inicial do rastreamento logístico.

POST

/logistic/{order_id}/pickup-ongoing

Parâmetros do Corpo (Payload)

Campo	Obrigatório	Descrição
driver_name	❌	Nome do entregador alocado.
driver_phone	❌	Telefone de contato do entregador.

Chegada no Estabelecimento

Informa que o entregador chegou fisicamente à loja e está pronto para coletar os itens. É um marco operacional crítico para que a loja agilize a entrega física do pacote ao profissional.

POST

/logistic/{order_id}/arrived-at-merchant

Início da Rota de Entrega

Confirma que o pedido foi coletado na loja e o entregador está oficialmente em rota final para o endereço do cliente. Este status define a transição da responsabilidade da loja para a fase de transporte.

POST

/logistic/{order_id}/delivery-ongoing

Chegada no Cliente

Sinaliza que o entregador chegou ao destino final e encontra-se no endereço de entrega. Este marco melhora o aviso ao cliente antes da conclusão definitiva.

POST

/logistic/{order_id}/arrived-at-customer

Confirmação de Entrega

Confirma que o pedido foi entregue com sucesso ao cliente final. Representa o fechamento do ciclo de vida logístico e a confirmação final da transação.

POST

/logistic/{order_id}/order-delivered

Entrega Cancelada / Insucesso na Alocação (DELIVERY_CANCELED)

Informa à plataforma que a entrega não pôde ser alocada ou que houve um problema/insucesso operacional com o entregador parceiro. Este endpoint serve para alertar a loja imediatamente sobre a impossibilidade de realizar a entrega do pedido.

POST

/logistic/{order_id}/delivery-canceled

Parâmetros do Corpo (Payload)

Campo	Obrigatório	Descrição
reason	❌	Justificativa, motivo ou nota textual opcional informando a razão do insucesso ou cancelamento da entrega.

Regras Específicas (Status DELIVERY_CANCELED)

• Flexibilidade Temporal: O integrador pode enviar esta atualização a qualquer momento do ciclo logístico, não sendo obrigado a seguir nenhuma sequência prévia de estados.
• Ciclo Reiniciável: Caso o problema seja resolvido e o pedido seja reatribuído a um novo entregador, o sistema permite reiniciar o ciclo normalmente a partir do status inicial (PICKUP_ONGOING), sem aplicar travas operacionais.