002_Manual_Pool_v2

Prévia do material em texto

Documentação técnica Pool de Pedidos 
Versão 2 
 
Atualizações do documento 
 
Versão Responsável Data Descrição 
v.1 Marcos Juliano Santos -PO 27/05/2022 Criação do documento 
v.2 Matheus Freire Drulla – Analista 07/06/2023 Atualização do documento 
 
 
SUMÁRIO 
INTRODUÇÃO ......................................................................................................................................................................................... 3 
DEFINIÇÕES ............................................................................................................................................................................................ 3 
 
Tipos de pedidos ............................................................................................................................................................................. 2 
Momento do pedido........................................................................................................................................................................ 3 
Canais de venda .............................................................................................................................................................................. 3 
Ciclo de vida do pedido .................................................................................................................................................................. 3 
Status do pedido ............................................................................................................................................................................. 4 
FLUXO DE INTEGRAÇÃO ...................................................................................................................................................................... 4 
Autorização ..................................................................................................................................................................................... 4 
Recepção de pedidos ...................................................................................................................................................................... 5 
Consultar novos pedidos ................................................................................................................................................................. 5 
Estrutura do evento ........................................................................................................................................................................ 6 
Filtros .............................................................................................................................................................................................. 6 
 Filtrar por Merchants (Lojas) ......................................................................................................................................................... 6 
Acknowledgment............................................................................................................................................................................. 7 
Confirmação ................................................................................................................................................................................... 7 
Obter detalhes do pedido............................................................................................................................................................... 7 
Payload........................................................................................................................................................................................... 8 
Informações gerais .................................................................................................................................................................... 9 
Merchant ................................................................................................................................................................................... 9 
Andress ...................................................................................................................................................................................... 9 
Contacts .................................................................................................................................................................................. 10 
Customer ................................................................................................................................................................................. 10 
Delivery .................................................................................................................................................................................... 11 
DeliveryAndress ....................................................................................................................................................................... 11 
 
2 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
Itens ......................................................................................................................................................................................... 11 
Total ......................................................................................................................................................................................... 12 
Payments ..................................................................................................................................................................................12 
Atualizar dados e status do pedido .............................................................................................................................................. 13 
AMBIENTE ......................................................................................................................................................................................... 
15 
Desenvolvimento .......................................................................................................................................................................... 15 
Homologação ................................................................................................................................................................................ 15 
Produção ...................................................................................................................................................................................... 15 
 
 
 
3 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
 
INTRODUÇÃO 
Através da API do Pool de Pedidos, fornecemos aos parceiros logísticos a capacidade de integrar os pedidos de 
entrega diretamente em seu sistema, facilitando o processo de gestão e execução das entregas. 
DEFINIÇÕES 
A API do Pool de Pedidos é uma interface de programação de aplicativos que permite que os parceiros logísticos se 
conectem de forma eficiente ao nosso sistema de pedidos de delivery. Essa integração simplifica o fluxo de trabalho, 
permitindo que os parceiros recebam e processem os pedidos de entrega diretamente em seu próprio sistema, 
otimizando assim a gestão e a execução das entregas. 
Tipos de pedidos 
 
No Pool de Pedidos será disponibilizado tão somente pedidos de DELIVERY. 
Order Type Descrição 
DELIVERY Pedidos que devem ser entregues no endereço escolhido pelo cliente. 
 
Momento do pedido 
 
Todos os pedidos serão preparados imediatamente e devem ser enviados o mais breve possível. 
Order Timing Descrição 
IMMEDIATE Pedidos que devem ser preparados imediatamentee enviados o mais breve 
possível. 
 
Canais de venda 
 
Canal de vendas pelo qual o pedido entra na plataforma (novos canais podem ser adicionados). 
 
Sales Channel Descrição Código de confirmação finalização da rota 
IFood Pedidos realizados através do Ifood. Sim 
Grupo Madero Pedidos realizados através do app Madero. Sim 
Rappi Pedidos realizados através do Rappi. Não 
Pede Pronto Pedidos realizados através do Pede Pronto. Não 
 
Ciclo de vida do pedido 
 
 
4 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
A API é orientada a eventos, sendo assim, um pedido pode ter mais de evento vinculados a ele. Segue um diagrama 
com os possíveis status de um pedido. 
 
Sales Channel Descrição 
Avaliable Evento que indica que o pedido está disponível para o serviço de entrega. 
Packaged Evento que indica que a produção do pedido foi finalizada. 
Unavaliable Evento que indica que o pedido está indisponível para o serviço de entrega. 
Cancelled Evento que indica que o pedido está cancelado. 
 
Status do pedido 
 
Para o devido rastreamento e melhor gestão, os pedidos devem receber as devidas atualizações de status. 
Sales Channel Descrição 
EnRouteToPickup Entregador alocou o pedido e está a caminho da coleta. 
ArrivedAtPickup Entregador chegou na filial para retirada do pedido. 
EnRouteToDropoff O pedido foi coletado e o entregador está a caminho para realizar a entrega. 
ArrivedAtDropoff Entregador chegou no endereço de entrega. 
Completed Entrega concluída. 
Canceled Entrega cancelada. 
Relocated Entregador foi realocado e está a caminho da coleta 
Returned Não foi possível finalizar a entrega e o pedido retornou a filial 
 
FLUXO DE INTEGRAÇÃO 
Autorização 
 
Para garantir a segurança dos dados fornecidos e identificar o cliente, todos os endpoints da API requerem autenticação. 
O acesso é concedido através de um token exclusivo, gerado pelo Grupo Madero para cada cliente. Para autenticar, é 
necessário incluir o token fornecido no cabeçalho (headers) de todas as requisições. Isso pode ser feito seguindo as 
instruções abaixo. 
 
 
5 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
Para efetuar a autenticação, você deve incluir o token fornecido no cabeçalho (headers) de todas as requisições, 
utilizando os dados abaixo: 
 
Campo Tipo Descrição 
x-functions-key string Token de acesso gerado. 
 
 
No caso de falha na autenticação, a API retornará o código de resposta 401. Esse código indica que a requisição não foi 
autorizada devido à falta ou inválida autenticação. Portanto, ao receber esse código, é necessário revisar as informações 
de autenticação fornecidas e garantir que o token esteja correto no cabeçalho da requisição. Se persistirem os 
problemas de autenticação, entre em contato com o Grupo Madero para obter assistência adicional. 
 
Recepção de pedidos 
 
Consultar novos pedidos 
 
Para receber os novos pedidos, é necessário fazer requisições no endpoint de polling regularmente, com um intervalo 
de 30 segundos. Sempre que ocorrer um novo evento, você receberá uma resposta com o código 200, juntamente com 
a lista de eventos associados. No entanto, se não houver novos eventos no momento, você ainda receberá uma resposta 
com o código 200, mas a lista de eventos estará vazia. 
Esse fluxo de polling garante que você seja notificado sobre os novos pedidos assim que estiverem disponíveis, 
permitindo uma integração em tempo real com o sistema de pedidos. Lembre-se de implementar esse processo de 
polling em seu código para receber as atualizações oportunamente. 
 
GET https://fn-hml-delivery-pool.azurewebsites.net/api/Polling 
 Por quanto tempo que os pedidos e eventos são disponibilizados? 
 
6 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
 Os pedidos e eventos são mantidos pela API até as 04h00 do dia seguinte à data do pedido, após esse período eles não 
são mais retornados.. 
 Ordenação dos eventos 
 
Os eventos não são entregues necessariamente de maneira ordenada. Caso seja necessário, após obter o 
detalhamento de todos os pedidos você pode ordenar pelo createdAt 
 
A API adota uma abordagem orientada a eventos, permitindo que um pedido possua múltiplos eventos associados. 
Esses eventos representam diferentes etapas e atualizações ocorridas ao longo do ciclo de vida do pedido. 
 
Estrutura do evento 
 
Campo Tipo Descrição 
id uuid Identificador único do pedido. 
status enum Status do pedido. 
 
Exemplo: 
 
Filtros 
 
É possível filtrar os pedidos que deseja receber utilizando a consulta mencionada acima 
 
Filtrar por Merchants (Lojas) 
 
 
Por padrão, o endpoint de polling retorna todos os eventos de todos os merchants aos quais o token da requisição tem 
acesso. No entanto, é possível especificar o merchant desejado na requisição para receber apenas os eventos 
relacionados a ele. Para isso, inclua na sua requisição as informações do merchant conforme o exemplo abaixo: 
GET https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001 
 
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001
 
7 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
Substitua <0a0000aa-0aa0-00aa-aa00-0000aa000001> pelo identificador único do merchant desejado. Dessa forma, a 
resposta da requisição incluirá apenas os eventos associados a esse merchant específico, em vez de todos os merchants 
disponíveis. Certifique-se de fornece o identificador correto do merchant na sua requisição para receber os eventos 
desejados. 
 Rate Limit 
 É importante observar que os eventos não são entregues em ordem necessariamente. Se você precisar, é possível 
ordenar os pedidos pelo campo "createdAt" após obter todos os detalhes. 
 
Confirmação 
 
Para evitar o recebimento de eventos duplicados, é necessário enviar uma confirmação assim que novos eventos 
forem recebidos pela API.Essa confirmação informa à API que o evento foi recebido e processado com sucesso, 
impedindo o reenvio do mesmo evento. É uma prática importante para manter a sincronização adequada entre a sua 
integração e a API. 
ACKNOWLEDGMENT 
 
POST https://fn-hml-delivery-pool.azurewebsites.net/api/Acknowledgment 
 
Campo Tipo Obrigatório Descrição 
id uuid Sim Identificador único do pedido. 
status enum Sim Status do pedido. 
 
No corpo da request, você pode enviar um array de eventos. 
Exemplo: 
 
 
Recomendações importantes: 
• Faça uma request de acknowledgment para cada request de polling. 
https://fn-hml-delivery-pool.azurewebsites.net/api/Acknowledgment
https://fn-hml-delivery-pool.azurewebsites.net/api/Acknowledgment
https://fn-hml-delivery-pool.azurewebsites.net/api/Acknowledgment
https://fn-hml-delivery-pool.azurewebsites.net/api/Acknowledgment
https://fn-hml-delivery-pool.azurewebsites.net/api/Acknowledgment
https://fn-hml-delivery-pool.azurewebsites.net/api/Acknowledgment
https://fn-hml-delivery-pool.azurewebsites.net/api/Acknowledgment
https://fn-hml-delivery-pool.azurewebsites.net/api/Acknowledgment
 
8 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
• Caso receba eventos que não sejam utilizados pelo seu aplicativo, envie o acknowledgment desses eventos 
mesmo assim para que não fique recebendo-os a cada polling novamente. Recomendamos que esse seja o 
tratamento padrão para todo evento ainda não mapeado no seu aplicativo. 
• Só é preciso enviar acknowledgment do evento uma única vez. 
 
Obter detalhes do pedido 
 
O endpoint retorna o código 200 juntamente com o conteúdo do pedido quando é fornecido um ID válido na 
requisição. No entanto, se um ID inválido ou o ID de um pedido antigo for informado, o endpoint retornará o código 
404, indicando que o pedido não foi encontrado. Certifique-se de fornecer um ID válido e atualizado para obter os 
detalhes corretos do pedido. 
GET https://fn-hml-delivery-pool.azurewebsites.net/api/Orders/0a0000aa-0aa0-00aa-aa00-0000aa000001 
 
 Pedidos antigos 
A API mantém os pedidos e eventos até 04h00 do dia subsequente a data do pedido. Cuidado para não consultar 
repetidamente pedidos antigos para evitar ser bloqueado temporariamente devido ao rate limit. 
 
Payload 
 
Nessa seção você encontrará todos os detalhes do payload de um pedido. Um pedido contém as seguintes 
informações: 
 
9 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
• Informações gerais - id, data de criação do pedido dentre outros. 
• Merchant - identificação do merchant (loja) 
• Customer - identificação do cliente que deve receber o pedido 
• Itens - produtos/pratos 
• Benefits - cupons de desconto incentivos 
• Additional Fees - taxas adicionais 
• Total - somatório dos valores do pedido 
• Payments - detalhes sobre as formas de pagamento 
• Delivery - informações sobre a forma de entrega do pedido e o endereço 
• Lat/long da localização do estabelecimento origem e do endereço final (cliente). 
Nossa API fornece todas as informações essenciais necessárias para que o parceiro logístico realize a entrega do 
pedido ao nosso cliente, além de outras funcionalidades adicionais. 
Informações Gerais 
 
Campo Tipo Descrição 
id uuid Identificador único do pedido. 
displayId string Id amigável para facilitar a identificação do pedido pela 
loja. Deve ser exibido na interface do seu aplicativo. 
salesChannel string Canal de vendas pelo qual o pedido entra na plataforma 
(novos canais podem ser adicionados). 
orderTiming enum Momento de entrega do pedido. 
preparationTimeInSeconds integer Estimativa do fim do preparo do pedido. 
createdAt date Data de criação do pedido. 
 
Exemplo: 
 
Merchant 
 
Campo Tipo Descrição 
id uuid Identificador único do Merchant (loja). 
name string Nome do merchant (loja). 
 
10 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
observations string Observações relacionadas ao processo de coleta do pedido 
(Ex.: Coletar o pedido pela porta lateral) 
 
Exemplo: 
 
Andress 
 
Campo Tipo Descrição 
streetName string Nome da rua ou avenida. 
streetNumber string Número (Obs: pode conter letras). 
neighborhood string Bairro ou setor. 
city string Cidade. 
state string Estado. 
country string País. 
reference string Ponto de referência. 
coordinates.latitude double Latitude. 
coordinates.longitude double Longitude. 
 
 
Exemplo: 
 
Contacts 
 
Campo Tipo Descrição 
phone string Número de telefone com DDD do Merchant (loja). 
email string Endereço de email do Merchant (loja). 
 
 
11 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
Exemplo: 
 
Customer 
 
Campo Tipo Descrição 
name string Nome do cliente. 
phone string 0800 para contato com o cliente. (Obs: o 0800 estará 
disponível tão somente para pedidos onde o salesChannel 
for igual a DLV_IFO ou DLV_ALP). 
localizer string Código localizador que deve ser informado ao ligar para o 
número 0800. 
 
Exemplo: 
 
 
Delivery 
 
Campo Tipo Descrição 
deliveryAndress -- Endereço onde o pedido deve ser entregue 
 
Exemplo: 
 
 
DeliveryAndress 
 
Campo Tipo Descrição 
deliveryAndress.streetName string Nome da rua ou avenida. 
deliveryAndress.streetNumber string Número (Obs: pode conter letras). 
deliveryAndress.complement string Complemento (Ex: Apartamento, Quadra, Lote). 
deliveryAndress.neighborhood string Bairro ou setor. 
 
12 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
deliveryAndress.city string Cidade. 
deliveryAndress.state string Estado. 
deliveryAndress.country string País. 
coordinates.latitude double Latitude. 
coordinates.longitude double Longitude. 
 
Exemplo: 
 
 
Itens 
 
Campo Tipo Descrição 
id uuid Identificador único do item. 
name string Nome do item. 
quantity integer Quantidade do item. 
unitPrice double Preço unitário. 
price double Preço do item: price = quantity x unitPrice. 
optionsPrice double Preço dos complementos (options). 
discount double Valor de desconto sobre o item. 
totalPrice double preço total (totalPrice = price + optionsPrice - discount) 
index integer posição/ordem dos itens 
 
Exemplo: 
 
13 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
 
 
Total 
 
Campo Tipo Descrição 
subtotal double Somatório do valor dos itens. 
deliveryFee double Valor da taxa de entrega. 
additionalFees double Somatório das taxas adicionais. 
benefits double Somatório dos benefits (cupons de desconto). 
orderAmount double Valor total do pedido (orderAmount = subTotal + 
deliveryFee + additionalFees - benefits). 
 
Exemplo: 
 
 
Payments 
 
Campo Tipo Descrição 
value double Valor do pagamento. 
type double Tipo de pagamento: ONLINE (pagamento já foi feito online 
pelo aplicativo e não deve ser cobrado na entrega) ou 
OFFLINE (pagamento deve ser feito no ato da entrega do 
pedido). 
prepaid double Valor que já foi pago (ONLINE). 
pending double Valor pendente que deve ser cobrado no ato da entrega 
(OFFLINE). 
 
 
14 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
Exemplo: 
 
 
 
Atualizar dados e status do pedido 
 
Após confirmar e obter os detalhes do pedido, é necessário atualizar o statuse os dados do pedido. Para confirmar 
um pedido, utilize o endpoint POST /Orders. 
Em caso de sucesso, você receberá o código de resposta 201 (Aceito). No entanto, é importante observar que uma 
solicitação de atualização pode ser descartada por diversos motivos, como quando o pedido já foi cancelado 
anteriormente. Certifique-se de lidar adequadamente com as respostas e tratar os possíveis cenários de descarte de 
solicitações de atualização. 
POST https://fn-hml-delivery-pool.azurewebsites.net/api/Orders 
Campo Tipo Obrigatório Descrição 
id uuid Sim Identificador único do pedido (madero). 
order_id uuid Sim Identificador único do pedido (parceiro). 
order_tracking_url string Sim Url para tracking do pedido. 
courier_trip.dropoff_instructions string Não Instruções para entrega do pedido. 
courier_trip.courier.id uuid Sim Identificador único do entregador. 
courier_trip.courier.first_name string Sim Nome do entregador. 
courier_trip.courier.last_name string Não Sobrenome do entregador. 
courier_trip.courier.location. latitude double Sim Latitude do entregador no momento em que 
ocorreu a atualização de status. 
courier_trip.courier.location. longitude double Sim Longitude do entregador no momento em que 
ocorreu a atualização de status. 
courier_trip.courier.vehicle. form_factor string Sim Tipo do veículo. 
courier_trip.courier.vehicle. make string Não Marca do veículo. (Aplicável ao carro e moto). 
courier_trip.courier.vehicle. model string Não Modelo do veículo. (Aplicável ao carro e moto). 
courier_trip.courier.vehicle. license_plate string Sim (Carro e 
Moto) 
Placa do veículo. (Aplicável ao carro e moto). 
estimate_date Timestamp 
milliseconds 
Sim Tempo estimado para concluir a entrega do 
pedido (Coleta + Entrega). 
status enum Sim Status da entrega. 
 
15 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
estimate_distance double Sim Distância estimada para concluir a entrega do 
pedido (Coleta + Entrega). 
related_id uuid Não Identificador único do pedido (Madero) 
(Aplicável apenas para pedidos roteirizados). 
confirmation_code string Sim (Apenas 
para o status 
Completed) 
Código de 4 números, que será informado pelo 
cliente, para a finalização da rota. (Utilizados 
para Grupo Madero e Ifood) 
 
 
 Código de confirmação para finalização da rota 
O código de confirmação para conclusão da rota é obrigatório apenas quando encaminhado o status “Completed”, e em 
pedidos cuja o canal de venda está devidamente habilitado para o uso do código. Consultar a seção “Canais de Venda” 
para obter maiores detalhes. 
 
 Impossibilidade de informar o código de confirmação 
Exemplo: 
Para casos em que o entregador se encontra impossibilidade de informar o código de confirmação (problemas 
sistêmicos, cliente não informou o código), poderá ser utilizado o código master para finalizar a rota. As rotas 
finalizadas através do código master serão devidamente auditadas. 
 
16 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
 
Código Master: 7676a7c0-04f7-4ade-8643-a6180c6f36ea 
 
 
Response 
Código Tipo Mensagem Descrição 
201 Success Accepted Status e dados atualizados com sucesso. 
409 Bad request Order already Taken Pedido já foi apropriado por outra plataforma. 
409 Bad request Order cancelled Pedido cancelado. 
409 Bad request RelatedId can't be same as Id O related_id deve ser diferente do id. 
409 Bad request Order not found Pedido não localizado. 
401 Unauthorized 
404 Not Found 
500 Internal Server Error Erro não mapeado. 
 
AMBIENTE 
Desenvolvimento 
fn-dev-delivery-pool.azurewebsites.net/ 
 
17 
 
 
Manual de Sistema Delivery 
Control – Pool de Pedidos 
07/06/2023 
Homologação 
fn-hml-delivery-pool.azurewebsites.net/ 
Produção deliverycontrol-
pool.grupomadero.com.br/