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 eventos

Obter 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:

Açõ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 /assignDriver

O 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)

Exemplo

{
  "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 /dispatch

Confirmaçã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 /verifyDeliveryCode

O aplicativo deve enviar os dados no payload:

• code <string> - Código de Verificação de Entrega que informado pelo cliente

Exemplo

{
  "code": "9999"
}

Nesta etapa, o aplicativo deverá validar através do evento “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 excludeHeartbeat para evitar que a loja fique aberta indevidamente; Utilize o header x-polling-merchants sempre 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;
  • 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.
  • 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.

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.

Preparação

Antes de iniciar, tenha em mãos os dados da sua loja de teste, como id e nome da loja. Certifique-se de ter acesso a um serviço de internet estável

Duração

No horário agendado, um analista do nosso time fará o acesso remoto para acompanhar cada etapa dos testes. O processo dura em média 45 minutos.

Reagendamento

Caso seu aplicativo não seja homologado, nosso time registrará no ticket os requisitos que não foram atendidos e você deverá ajustar seu software. Você poderá agendar uma nova homologação 15 dias depois da tentativa anterior.