Madero_-_Manual_Pool_v3_1

Prévia do material em texto

Documentação técnica Pool de Pedidos 
Versão 
1 
 
Atualizações do documento 
Versão Responsável Data Descrição 
v.1 Marcos Juliano Santos - 41 9 8747-4744 27/05/2022 Criação do documento 
v.2 Marcos Juliano Santos - 41 9 8747-4744 03/10/2022 Atualização do documento 
v.3 Marcos Juliano Santos - 41 9 8747-4744 12/12/2022 Atualização do documento 
SUMÁRIO 
INTRODUÇÃO ...................................................................................................................................................................................... 2 
DEFINIÇÕES ......................................................................................................................................................................................... 2 
Tipos de pedidos ............................................................................................................................................................................. 2 
Momento do pedido....................................................................................................................................................................... 2 
Canais de venda .............................................................................................................................................................................. 2 
Ciclo de vida do pedido .................................................................................................................................................................. 2 
Status do pedido ............................................................................................................................................................................. 3 
FLUXO DE INTEGRAÇÃO ...................................................................................................................................................................... 3 
Autorização ..................................................................................................................................................................................... 3 
Recepção de pedidos ...................................................................................................................................................................... 3 
Consultar novos pedidos ................................................................................................................................................................ 3 
Estrutura do evento ........................................................................................................................................................................ 4 
Filtros .............................................................................................................................................................................................. 4 
Filtrar por Merchants (Lojas) ...................................................................................................................................................... 4 
Acknowledgment de eventos ......................................................................................................................................................... 4 
Confirmação ................................................................................................................................................................................... 5 
Obter detalhes do pedido............................................................................................................................................................... 5 
Informações gerais ..................................................................................................................................................................... 6 
Merchant .................................................................................................................................................................................... 6 
Andress ....................................................................................................................................................................................... 6 
Contacts ..................................................................................................................................................................................... 7 
Customer .................................................................................................................................................................................... 7 
Delivery ...................................................................................................................................................................................... 8 
DeliveryAndress ......................................................................................................................................................................... 8 
Items .......................................................................................................................................................................................... 8 
Total ........................................................................................................................................................................................... 9 
Payments .................................................................................................................................................................................... 9 
Atualizar dados e status do pedido .............................................................................................................................................. 10 
AMBIENTE ......................................................................................................................................................................................... 11 
Desenvolvimento .......................................................................................................................................................................... 11 
Homologação ................................................................................................................................................................................ 11 
Produção ...................................................................................................................................................................................... 11 
 
 
Manual de Sistema 
Delivery Control 15/12/2022 
 
 
TI Sistemas 
INTRODUÇÃO 
A API do Pool de Pedidos permite que o parceiro logístico integre os pedidos de delivery a seu sistema de entregas. 
DEFINIÇÕES 
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 imediatamente e 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 
99 Food Pedidos realizados através do 99 Food. Não 
Pede Pronto Pedidos realizados através do Pede Pronto. Não 
 
Ciclo de vida do pedido 
 
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. 
 
Manual de Sistema 
Delivery Control 15/12/2022 
 
 
TI Sistemas 
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. 
 
FLUXO DE INTEGRAÇÃO 
Autorização 
 
Para identificação do client e visando garantir segurança em todos os dados fornecidos, todos os endpoints da API 
exigem autenticação. O Acesso é concedido via Token, gerado pelo Grupo Madero a cada client. 
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. 
 
Caso ocorra falha ao se autenticar, você receberá o código de resposta 401. 
 
Recepção de pedidos 
 
Consultar novos pedidos 
 
Para receber novos pedidos, você deve fazer requests no endpoint de polling regularmente a cada 30 segundos. 
Sempre que houver um novo evento você receberá o código de resposta 200 com a lista de eventos. Caso não existam 
novos eventos, você receberá o código de resposta 200 e uma lista vazia. 
 
Manual de Sistema 
Delivery Control 15/12/2022 
 
 
TI Sistemas 
GET https://fn-hml-delivery-pool.azurewebsites.net/api/Polling 
 
 
 
 
 
 
 
A API é orientada a eventos. Um pedido pode então ter vários eventos vinculados. 
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 você deseja receber. 
 
Filtrar por Merchants (Lojas) 
 
Por padrão, esse endpoint retorna todos os eventos de todos os merchants aos quais o token da request têm 
acesso. É possível informar na request de qual Merchant você deseja receber eventos. Exemplo: 
GET https://fn-hml-delivery-pool.azurewebsites.net/api/Polling?storeId=0a0000aa-0aa0-00aa-aa00-0000aa000001 
 
Acknowledgment de eventos 
 
 
 
Por quanto tempo que os pedidos e eventos são disponibilizados? 
A API mantém os pedidos e eventos até 04h00 do dia subsequente a data do pedido. Depois desse período os 
eventos 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 
 
 
Rate Limit 
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 
 
 
 
Manual de Sistema 
Delivery Control 15/12/2022 
 
 
TI Sistemas 
Confirmação 
 
Ao receber novos eventos, você sempre deve enviar a confirmação para que a API não te envie esse mesmo evento 
novamente. 
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. 
• 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 
 
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. 
GET https://fn-hml-delivery-pool.azurewebsites.net/api/Orders/0a0000aa-0aa0-00aa-aa00-0000aa000001 
 
 
 
 
Nessa seção você encontrará todos os detalhes do payload de um pedido. Um pedido contém as seguintes 
informações: 
• 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 
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. 
 
 
https://developer.ifood.com.br/pt-BR/docs/references#operations-Events-acknowledgeEvents
 
Manual de Sistema 
Delivery Control 15/12/2022 
 
 
TI Sistemas 
• 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 
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). 
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. 
 
Manual de Sistema 
Delivery Control 15/12/2022 
 
 
TI Sistemas 
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). 
 
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: 
 
 
 
 
 
Manual de Sistema 
Delivery Control 15/12/2022 
 
 
TI Sistemas 
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. 
deliveryAndress.city string Cidade. 
deliveryAndress.state string Estado. 
deliveryAndress.country string País. 
coordinates.latitude double Latitude. 
coordinates.longitude double Longitude. 
 
Exemplo: 
 
Items 
 
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. 
optionsPricedouble 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 
 
 
Manual de Sistema 
Delivery Control 15/12/2022 
 
 
TI Sistemas 
Exemplo: 
 
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). 
 
Exemplo: 
 
 
 
Manual de Sistema 
Delivery Control 15/12/2022 
 
 
TI Sistemas 
 
Atualizar dados e status do pedido 
 
Após confirmar e obter os detalhes do pedido, você deve realizar a atualização do status e dados do pedido. Para 
confirmar um pedido você deve utilizar o endpoint: POST /Orders 
Em caso de sucesso na solicitação, você receberá o código de resposta 201 (accepted). É possível que uma request 
de atualização seja descartada por alguns motivos, dentre eles, por exemplo, se o pedido já havia sido cancelado 
anteriormente. 
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. 
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. 
 
 
 
 
 
 
Exemplo: 
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 
Para casos em que o entregador encontra-se 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. 
Código Master: 7676a7c0-04f7-4ade-8643-a6180c6f36ea 
 
 
https://developer.ifood.com.br/en-US/docs/references#operations-Actions-confirm
 
Manual de Sistema 
Delivery Control 15/12/2022 
 
 
TI Sistemas 
 
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/ 
Homologação 
fn-hml-delivery-pool.azurewebsites.net/ 
Produção 
deliverycontrol-pool.grupomadero.com.br/