Introdução

A integração com a API do parceiro foi desenvolvida com o propósito de simplificar e automatizar o processo de integração de pedidos provenientes de marketplaces de delivery, essa funcionalidade permite que parceiros com interesse em realizar a integração de seus pedidos possam desenvolver ou atualizar suas APIs para integração dos pedidos com o Consumer.

O Consumer atualmente possui a disponibilidade de integração de três eventos.

  1. Consulta do evento: Esta função de polling permite que o Consumer consulte os eventos de venda disponíveis na API do parceiro.
  2. Consulta detalhes do pedido: Com base no ID do pedido, esta função permite consultar a API do parceiro para que ela possa retornar todos os detalhes específicos de um pedido, incluindo informações sobre pagamento, produtos, clientes e outros detalhes relevantes.
  3. Envio de alteração do status do pedido: O Consumer envia para a API do parceiro todas as atualizações de status, incluindo confirmação, cancelamento, saída para entrega e conclusão do pedido.

Ao longo desta documentação, você encontrará informações detalhadas sobre cada função que o parceiro deve desenvolver para integrar corretamente seus pedidos ao Consumer, incluindo parâmetros de entrada, respostas esperadas e exemplos de uso.

Ciclo de vida do pedido

A integração é orientada a eventos, sendo assim, um pedido pode ter vários eventos vinculados. Abaixo um diagrama com os possíveis status de um pedido.

Fluxo de integração

Etapas de integração de um pedido que a API do parceiro deve possuir.

Atenção: Para todas as requisições aos endpoints listados, o Consumer enviará um cabeçalho Authorization contendo um token do tipo Bearer. Este token deve ser previamente configurado na integração dentro do Consumer.

Bearer Autenthication 

Did not find whats you were looking for? Ask the community Found a mistake? Lets us Know 

https://swagger.io/docs/specification/authentication/bearer-authentication/

Consulta de eventos

Para identificar e receber novos pedidos o Consumer faz requests no endpoint de polling da API do parceiro regularmente.

Esse endpoint deve retornar o código 200 e as informações iniciais do pedido.

GET /api/polling
Code: 200 Success
Response body

{
"items": [
{
"id": "9da87be4-77f5-4bf7-9fdc-514e2d3c679b",
"orderId": "74df5c78-10cd-46c0-99a1-a0439841f683",
"createdAt": "2024-04-10T15:41:30.6960049Z",
"fullCode": "PLACED",
"code": "PLC"
}
],
"statusCode": 0,
"reasonPhrase": null
}

Consulta detalhes do pedido

Antes de confirmar ou cancelar um pedido o Consumer obtêm os detalhes do mesmo, para que o usuário possa verificar se conseguirá preparar e entregar o pedido, sendo assim possível validar se possui todos os itens necessários em estoque e a disponibilidade para efetuar a entrega no endereço do cliente.

Esse endpoint deve retornar o código 200 e todo o conteúdo do pedido.

GET /api/order/74df5c78-10cd-46c0-99a1-a0439841f683
Code: 200 Success
Responde body

{
"item": {
"benefits": null,
"orderType": "DELIVERY",
"payments": {
"methods": [
{
"method": "CREDIT",
"prepaid": false,
"currency": "BRL",
"type": "OFFLINE",
"value": 51.97,
"cash": null,
"card": {
"brand": "AMEX"
},
"wallet": null
}
],
"pending": 51.97,
"prepaid": 0
},
"merchant": {
"name": "Teste - Consumer Soluções em Tecnologia Ltda",
"id": "2eff44c8-ff06-4507-8233-e3f72c4e59af"
},
"salesChannel": "PARTNER",
"picking": null,
"orderTiming": "IMMEDIATE",
"createdAt": "2024-04-10T15:41:30.6960049Z",
"total": {
"benefits": 0,
"deliveryFee": 3.99,
"orderAmount": 51.97,
"subTotal": 47.98,
"additionalFees": 0
},
"preparationStartDateTime": "2024-04-10T15:41:30.6960049Z",
"id": "74df5c78-10cd-46c0-99a1-a0439841f683",
"displayId": "8078",
"items": [
{
"unitPrice": 23.99,
"quantity": 2,
"externalCode": "106",
"totalPrice": 47.98,
"index": 1,
"unit": "UN",
"ean": null,
"price": 47.98,
"observations": null,
"imageUrl": "https://seusite.com.br/image/e078d2e1-0af0-49c3-ba0d-ea4effffbd54/202305121137_XIHJ_i.jpg",
"name": "Alabama - Teste",
"options": null,
"id": "09490b5d-153e-407a-a5f4-0cf2dfc0f7e0",
"uniqueId": "1b35e84b-7539-4f1e-bf0e-a46e1be0994b",
"optionsPrice": 0,
"addition": 0,
"scalePrices": null
}
],
"customer": {
"phone": {
"number": "0800 012 3456",
"localizer": "54639728",
"localizerExpiration": "2024-04-10T16:41:30.6960049Z"
},
"documentNumber": null,
"name": "PEDIDO DE TESTE - Fulano de Tal",
"ordersCountOnMerchant": null,
"id": "910a258a-bcd3-4564-a62b-d29c61c94985",
"segmentation": "Cliente"
},
"extraInfo": null,
"additionalFees": null,
"delivery": {
"mode": "DEFAULT",
"pickupCode": "1492",
"deliveredBy": "Partner",
"deliveryAddress": {
"reference": "TESTE",
"country": "XX",
"streetName": "Rua TESTE",
"formattedAddress": "Rua TESTE, 999999",
"streetNumber": "999999",
"city": "TESTE",
"postalCode": "99999999",
"coordinates": {
"latitude": 0,
"longitude": 0
},
"neighborhood": "Bairro TESTE",
"state": "XX",
"complement": "Complemento TESTE"
},
"deliveryDateTime": "2024-04-10T15:41:30.6960049Z",
"observations": null
},
"schedule": null,
"indoor": null,
"takeout": null,
"additionalInfometadata": null
},
"statusCode": 0,
"reasonPhrase": null
}

Alteração de status do pedido

Após obter os detalhes do pedido, o usuário do Consumer deve tomar uma decisão: confirmar ou cancelar o pedido.

Posteriormente o Consumer envia a alteração de status para a API do parceiro no formato abaixo:

Request URL
POST /api/order/status
Request body
{
"orderId": "74df5c78-10cd-46c0-99a1-a0439841f683",
"status": "DISPATCHED",
"justification": "O pedido saiu para a entrega"
}
Code: 200 Success
Responde body
{
"statusCode": 0,
"reasonPhrase": "74df5c78-10cd-46c0-99a1-a0439841f683 alterado para 'DISPATCHED': O pedido saiu para a entrega."
}

Integração dos produtos do pedido

Para uma integração correta dos itens do pedido no Consumer, o primeiro passo essencial é garantir o preenchimento dos códigos de PDV na plataforma do parceiro.

A API do parceiro precisa retornar o código do PDV para cada item do pedido, permitindo que o Consumer identifique claramente os itens contidos nele. O Consumer facilita esse processo, fornecendo todos os códigos de forma intuitiva e acessível.

Acesse as opções: PRODUTOS > PRODUTOS


Nessa tela é possível identificar o código PDV de todos os produtos, e caso necessário exportar para um arquivo “.xlsx”. A API do parceiro deve retornar no pedido o código PDV de cada produto ou complemento no campo “externalCode” como mostrado abaixo:
{
"unitPrice": 23.99,
"quantity": 2,
"externalCode": "106",
"totalPrice": 47.98,
"index": 1,
"unit": "UN",
"ean": null,
"price": 47.98,
"observations": null,
"imageUrl": "https://seusite.com.br/image/e078d2e1-0af0-49c3-ba0d-ea4effffbd54/202305121137_XIHJ_i.jpg",
"name": "Alabama - Teste",
"options": null,
"id": "09490b5d-153e-407a-a5f4-0cf2dfc0f7e0",
"uniqueId": "1b35e84b-7539-4f1e-bf0e-a46e1be0994b",
"optionsPrice": 0,
"addition": 0,
"scalePrices": null
}

Produtos por tamanho e complementos

Para produtos por tamanho com venda de múltiplos sabores, complementos e adicionais o código PDV também deve ser preenchido, veja as orientações abaixo:

Para obter o código PDV dos complementos acesse: PRODUTOS > COMPLEMENTOS

A API do parceiro deve seguir o exemplo de retorno baixo para adicionais, complementos e produtos por tamanho:
"items": [
{
"unitPrice": 0,
"quantity": 1,
//CODIGO DO TAMANHO OU DO PRODUTO PRINCIPAL
"externalCode": "T8",
"totalPrice": 36,
"index": 2,
"unit": "UN",
"ean": null,
"price": 0,
"observations": null,
"imageUrl": "https = //static-images.ifood.com.br/image/upload/t_high/pratos/e078d2e1-0af0-49c3-ba0d-ea4effffbd54/202305121137_XIHJ_i.jpg",
"name": "PEDIDO DE TESTE - GRA",
"options": [
{
"unitPrice": 18,
"unit": "UN",
"ean": null,
"quantity": 1,
//CODIGO DO PRODUTO PIZZA DE CALABRESA
"externalCode": "55",
"price": 18,
"name": "1/2 Calabresa",
"index": 3,
"id": "4cdce541-aca7-3d89-a1f5-962b7b70e1b6",
"addition": 0
},
{
"unitPrice": 17.5,
"unit": "UN",
"ean": null,
"quantity": 1,
//CODIGO DO PRODUTO PIZZA BAIANA
"externalCode": "133",
"price": 18,
"name": "1/2 Baiana",
"index": 4,
"id": "9c72066d-9529-3d3d-88b8-f05a35a8dfc1",
"addition": 0.5
},
{
"unitPrice": 0,
"unit": "UN",
"ean": null,
"quantity": 1,
//CODIGO DO COMPLEMENTO BORDA DE CATUPIRY
"externalCode": "4",
"price": 0,
"name": "Borda Catupiry",
"index": 5,
"id": "ba0d1375-5f6b-3a7e-8d75-7adf2b4b7de1",
"addition": 0
}
],

Configuração no Consumer

Para começar a utilizar a integração com a API do parceiro, o usuário do Consumer precisa acessar o sistema e inserir todas as informações necessárias, seguindo as orientações abaixo.

Acesse as opções: APPS > Pedidos Online > API do parceiro

Preencha todos os campos conforme exemplo abaixo:

Atenção: para garantir a correta identificação da loja em relação à API do parceiro integrado, é essencial preencher o campo “token” com o token fornecido pelo parceiro. Este token serve como uma chave de acesso exclusiva, permitindo uma integração eficiente e segura entre as plataformas.

Após preencher e validar corretamente todas as informações, a opção de ativar a integração na fila de pedidos online estará disponível.

Acesse as opções: APPS > Pedidos Online > Fila de Pedidos

Ative a fila de pedidos e o Consumer já estará pronto para receber os pedidos do parceiro.

Após ativar a fila de pedidos Online, os pedidos do parceiro vão ser integrados e exibidos para o atendimento.

Todos os pedidos confirmados pelo usuário são listados na aba de Pedidos Delivery, onde podem ser consultado todos os detalhes e produtos integrados no pedido.

Ao alterar o status do pedido, o Consumer envia essa alteração para a API do parceiro.

Este artigo foi útil para você?


Teste o Consumer Gr tis