Docs Logistics
A API de Logistics oferece recursos para gestão de entregas.Fluxo de integração
Recepção de pedidos
Consultar novos pedidos
Para receber novos pedidos, você deve fazer requests no endpoint de polling regularmente a cada 30 segundos ou registrar um webhook para receber eventosAo utilizar o Polling, o aplicativo é obrigatório usar o
excludeHeartbeat, dessa forma evitará que a loja fique aberta indevidamente.Ex: /events/v1.0/events:polling?excludeHeartbeat=trueUtilizando o polling para receber eventos de pedidos
Veja em detalhes sobre como utilizar o endpoint de polling para receber eventos de pedidosUtilizando o webhook para receber eventos de pedidos
Veja em detalhes sobre como utilizar o webhook para receber eventos de pedidosObter detalhes do pedido
É importante obter os detalhes do pedido para garantir que tenhamos as informações necessárias no momento de alocar um motorista. Isso nos permite conhecer o tamanho do pedido e atribuir o motorista mais adequado para uma entrega eficiente.Através do endpoint GET logistics/orders/{id} você pode obter todos os detalhes de um pedido.Esse endpoint retorna o código 200 e o conteúdo do pedido. Caso seja informado um id inválido na request ou o id de um pedido antigo o endpoint retorna 404.Nessa seção você encontrará todos os detalhes do payload de um pedido:Detalhes de um pedido
Veja em detalhes todos os campos que um pedido pode trazerAções de logística no pedido
Alocar uma pessoa entregadora para o pedido
Após obter os detalhes do pedido, o aplicativo deverá alocar uma pessoa entregadora para que a mesmo faça a coleta e entrega do pedido. Para isso, deve utilizar o endpoint: POST /assignDriverO aplicativo deve enviar os dados no payload:- workerName <string> - Nome da pessoa entregadora
- workerPhone <string> - Telefone da pessoa entregadora
- workerVehicleType <string> - Tipo do veículo
- ex: (BICYCLE, ONFOOT, PATINETE, EBIKE, SUPERBIKE, CAR, MOTORCYCLE, MOTORBIKE)
{
"workerName": "José Maria",
"workerPhone": "11999999999",
"workerVehicleType": "MOTORCYCLE"
}Notificação de Deslocamento para Coleta do Pedido
Após a alocação de uma pessoa entregadora para o pedido, o aplicativo deve notificar que a pessoa está a caminho do endereço de origem retirar o pedido. Para isso, utilize o endpoint: POST /goingToOrigin.Confirmação de Chegada na Origem para Coleta do Pedido
Quando a pessoa entregadora chegar ao local de origem para a coleta do pedido, é necessário utilizar o endpoint: POST /arrivedAtOrigin para confirmar a chegada e a intenção de retirar o pedido.Notificação de Deslocamento para Entrega do Pedido
Após a coleta do pedido, quando a pessoa entregadora estiver a caminho do destino, o aplicativo deve notificar o usuário utilizando o endpoint: POST /dispatchConfirmação de Chegada ao Destino para Entrega do Pedido
Quando a pessoa entregador chegar no local de destino, deve utilizar o endpoint: POST /arrivedAtDestination para confirmar a chegada e a disponibilidade para entrega do pedido.Verificação de Entrega
Enviar código de verificação de entrega
Para obter a Confirmação de Entrega, é necessário realizar a Verificação do Código de Entrega. A pessoa entregadora deve solicitar ao destinatário o código de entrega e digitá-lo. O aplicativo deve conseguir receber o código e enviá-lo através do endpoint POST /verifyDeliveryCodeEstá etapa é obrigatória para as Integradoras, visando padronizar e otimizar os fluxos logísticos, garantindo maior eficiência e confiabilidade no processamento de entregas.O aplicativo deve enviar os dados no payload:- code <string> - Código de Verificação de Entrega que informado pelo cliente
{
"code": "9999"
}“DELIVERY_DROP_CODE_REQUESTED” que será gerado no polling, se o pedido requer do Código de Verificação de Entrega. Caso este evento esteja associado ao pedido, o aplicativo deve chamar o endpoint POST /verifyDeliveryCode para concluir a entrega.Exemplo do evento:{
"id": "f24e3b11-d292-48f0-a74b-e984575a1a0a",
"code": "DDCR",
"fullCode": "DELIVERY_DROP_CODE_REQUESTED",
"orderId": "9c964c28-c833-44bb-9457-9b9accca3a6c",
"merchantId": "b8ce1930-463b-4794-80b4-1823c261c1fb",
"createdAt": "2023-04-17T17:56:39.029Z"
}Critérios para homologação
Esses critérios são aplicáveis para integradoras que desejam integrar exclusivamente com o módulo Logistics e realizar a operação de delivery para os Merchants.O aplicativo deve ser capaz de
- Receber eventos de pedidos via polling ou via webhook.
- No caso do polling:
- Fazer requests no endpoint de /polling regularmente para não perder nenhum pedido, passando o parâmetro
excludeHeartbeatpara evitar que a loja fique aberta indevidamente; Utilize o headerx-polling-merchantssempre que precisar filtrar eventos de um ou mais merchants. Também é possível filtrar os eventos que deseja receber por tipo e por grupo; - Enviar /acknowledgment para todos os eventos recebidos (com status code 200) imediatamente após a request de polling;
- Fazer requests no endpoint de /polling regularmente para não perder nenhum pedido, passando o parâmetro
- No caso do webhook: responder com sucesso às requests do webhook, verificado por nossa auditoria interna;
- Atualizar o status do Driver, avisando que o mesmo foi alocado para o Pedido através do endpoint POST /assignDriver
- Notificar o deslocamento do Driver, informando o que mesmo está indo ao endereço de origem para coletar o Pedido através do endpoint POST /goingToOrigin.
- Confirmar que o Driver chegou ao endereço de origem para coletar o pedido através do endpoint POST /arrivedAtOrigin.
- Notificar que o Driver coletou o pedido e está a caminho do endereço de entrega através do endpoint POST /dispatch .
- Notificar que o Driver chegou ao destino para realizar a entrega do pedido através do endpoint POST /arrivedAtDestination.
- Etapa obrigatória para todas Integradoras. Enviar o código de confirmação de entrega através do endpoint POST /verifyDeliveryCode. Nesta etapa, o aplicativo deve ser capaz de analisar se o pedido está elegível para realizar a validação do código pelo evento
“DELIVERY_DROP_CODE_REQUESTED”. Este evento será gerado e enviado para cada pedido elegível.
- No caso do polling:
Requisitos não funcionais
- Renovar o token somente quando estiver prestes a expirar ou imediatamente após a expiração.
- O aplicativo deve respeitar as políticas de rate limit de cada endpoint.
Como Agendar
Para agendar a homologação do seu aplicativo acesse a área de chamados e abra uma requisição para homologação do seu aplicativo. Nossa equipe entrará em contato com você para agendar o processo.Nova Tentativa
Antes de agendar a homologação do seu aplicativo certifique-se de que ele atende todos os requisitos listados acima. É preciso aguardar 15 dias para uma nova tentativa.