Introdução
A integração com a API do parceiro foi desenvolvida para simplificar e automatizar o processo de incorporação de pedidos provenientes de marketplaces de delivery, além de pedidos de mesa e comandas. Essa funcionalidade permite que parceiros interessados em integrar seus pedidos possam desenvolver ou atualizar suas APIs, facilitando a comunicação direta com o sistema Consumer.
Atualmente, o Consumer oferece suporte para a integração de quatro eventos principais:
- Consulta de eventos: Esta função de polling permite ao Consumer verificar os eventos de venda disponíveis na API do parceiro.
- Consulta de detalhes do pedido: Com base no ID do pedido, esta função possibilita a consulta à API do parceiro para obter todos os detalhes específicos de um pedido, incluindo informações sobre pagamento, produtos, clientes, e outros dados relevantes.
- Envio de detalhes do pedido: O Consumer comunica a API do parceiro todos os detalhes específicos de um pedido, incluindo informações sobre pagamento, produtos, clientes, e outros dados relevante
- Envio de atualização de status do pedido: O Consumer comunica à API do parceiro todas as atualizações de status, como confirmação, cancelamento, saída para entrega, e conclusão do pedido.
Nesta documentação, você encontrará informações detalhadas sobre cada função que o parceiro deve implementar para integrar seus pedidos ao Consumer de forma eficaz. Serão abordados os parâmetros de entrada, as respostas esperadas e exemplos práticos de uso.
O que é necessário para realizar a integração?
Para realizar a integração com o sistema Consumer, a empresa parceira precisa desenvolver uma API que siga as especificações descritas neste manual. Essa API permitirá que o Consumer consulte os eventos de pedidos diretamente na API do parceiro e troque informações de maneira eficiente e segura.
Os parceiros devem garantir que sua API esteja configurada para atender às quatros funcionalidades principais de integração listadas acima.
Atenção: Para utilizar ou testar a integração com a API do Parceiro, é necessário ter uma assinatura Premium do Consumer, que libera o acesso às funcionalidades avançadas. Se você for um terceiro, utilize a assinatura do cliente que o contratou para validar a integração, pois não há ambiente de desenvolvimento separado a implementação ocorre diretamente no ambiente do cliente.
Ciclo de Vida do Pedido
A integração é orientada por eventos, o que significa que um pedido pode passar por diversos eventos ao longo de seu ciclo de vida. Abaixo, você encontrará um diagrama ilustrando os possíveis status de um pedido.
Fluxo de Integração
Endpoint de Polling
O endpoint de polling permite que o Consumer consulte regularmente a API do parceiro para verificar a existência de novos pedidos, o Consumer vai realizar requisições periódicas ao endpoint de polling da API do parceiro.
Esse endpoint deve retornar código 200, com as informações iniciais do pedido.
Response Body Parameters
| Name | Type | Description | Required |
|---|---|---|---|
| id | string | Identificador único do item | Yes |
| orderId | string | Identificador único do pedido ao qual o item pertence | Yes |
| createdAt | string (DateTime) | Data e hora de criação do item no formato UTC ISO 8601 | Yes |
| fullCode | string | Status completo ou descritivo do pedido (Ex.: “PLACED, ORDER_DETAILS_REQUESTED”) | Yes |
| code | string | Código reduzido que representa o status do pedido (Ex.: “PLC, ODR”) | Yes |
| statusCode | int | Código de status da resposta da API (0 normalmente indica sucesso) | Yes |
| reasonPhrase | string | Frase de motivo ou descrição adicional sobre o status (pode ser nulo) | No |
Exemplo:
{ "items": [ { "id": "1b51b42a-f24d-4010-92b2-80bde30b6eb2", "orderId": "e1f4e4fa-58dd-4d76-9d19-e8a00d47f905", "createdAt": "2024-08-21T16:36:23.9733003Z", "fullCode": "PLACED", "code": "PLC" } ], "statusCode": 0, "reasonPhrase": null}
Endpoint de consulta de detalhes do pedido
O endpoint de consulta de detalhes do pedido permite que o Consumer tenha acesso às informações completas de um pedido específico. Antes de confirmar ou cancelar um pedido, o Consumer consulta esses detalhes para exibi-los ao cliente e, em seguida, realizar o atendimento. Para pedidos delivery isso garante que todos os itens estejam disponíveis em estoque e que a entrega possa ser efetuada no endereço do cliente.
Esse endpoint deve retornar um código 200, acompanhado de todas as informações detalhadas do pedido.
| Name | Type | Description | Required |
|---|---|---|---|
| id | string | Identificador único do pedido | Yes |
| displayId | string | ID exibido do pedido (número do pedido) | Yes |
| orderType | string | Tipo de pedido | Yes |
| salesChannel | string | Canal de vendas | Yes |
| orderTiming | string | Tempo do pedido | Yes |
| createdAt | string | Data e hora de criação do pedido no formato ISO | Yes |
| preparationStartDateTime | string | Data e hora de início da preparação | Yes |
| merchant.id | string | Identificador único do estabelecimento | Yes |
| merchant.name | string | Nome do estabelecimento | Yes |
| total.subTotal | float | Valor total dos produtos antes das taxas | Yes |
| total.deliveryFee | float | Taxa de entrega | Yes |
| total.orderAmount | float | Valor total do pedido, incluindo taxas | Yes |
| total.benefits | float | Benefícios ou descontos aplicados | No |
| total.additionalFees | float | Taxas adicionais, se houver | No |
| payments.methods.method | string | Método de pagamento | Yes |
| payments.methods.type | string | Tipo de pagamento | Yes |
| payments.methods.currency | string | Moeda | Yes |
| payments.methods.value | float | Valor pago com este método | Yes |
| payments.methods.card.brand | string | Bandeira do cartão (se pagamento for com cartão) | No |
| payments.pending | float | Valor pendente de pagamento | Yes |
| payments.prepaid | float | Valor pré-pago | No |
| customer.id | string | Identificador único do cliente | Yes |
| customer.name | string | Nome do cliente | Yes |
| customer.phone.number | string | Número de telefone do cliente | Yes |
| customer.phone.localizer | string | Localizador ou código de verificação do telefone | Yes |
| customer.phone.localizerExpiration | string | Data e hora de expiração do localizador no formato ISO | Yes |
| customer.documentNumber | string | Documento do cliente | No |
| delivery.mode | string | Modo de entrega | Yes |
| delivery.deliveredBy | string | Quem realiza a entrega | Yes |
| delivery.pickupCode | string | Código de retirada para o cliente | Yes |
| delivery.deliveryDateTime | string | Data e hora da entrega | Yes |
| delivery.deliveryAddress.country | string | País | Yes |
| delivery.deliveryAddress.state | string | Estado | Yes |
| delivery.deliveryAddress.city | string | Cidade | Yes |
| delivery.deliveryAddress.postalCode | string | CEP | Yes |
| delivery.deliveryAddress.streetName | string | Nome da rua | Yes |
| delivery.deliveryAddress.streetNumber | string | Número da rua | Yes |
| delivery.deliveryAddress.neighborhood | string | Bairro | Yes |
| delivery.deliveryAddress.complement | string | Complemento do endereço | No |
| delivery.deliveryAddress.reference | string | Referência do endereço | No |
| items.id | string | Identificador único do item | Yes |
| items.externalCode | string | Código externo do produto | Yes |
| items.name | string | Nome do produto | Yes |
| items.quantity | int | Quantidade do produto | Yes |
| items.unitPrice | float | Preço unitário do produto | Yes |
| items.totalPrice | float | Preço total (preço unitário * quantidade) | Yes |
| items.observations | string | Observações ou notas | No |
| items.imageUrl | string | URL da imagem do produto | No |
| items.options.name | string | Nome da opção do item (se houver) | No |
| items.options.quantity | int | Quantidade da opção | No |
| items.options.unitPrice | float | Preço unitário da opção | No |
| items.options.price | float | Preço total da opção | No |
| items.options.externalCode | string | Código externo da opção | No |
Exemplo:
Endpoint de envio dos detalhes do pedido
Este endpoint é responsável por enviar os detalhes de um pedido específico. Ao receber a requisição, o Consumer deve responder com todas as informações completas e atualizadas do respectivo pedido.
Inicialmente, o parceiro envia um evento por meio do polling da API do parceiro, com o objetivo de requisitar os detalhes do pedido.
Inicialmente, o parceiro envia um evento por meio do polling da API do parceiro, com o objetivo de requisitar os detalhes do pedido.
Request Path Parameter
| Name | Type | Description | Required |
|---|---|---|---|
| OrderId | string | Identificador único do pedido | Yes |
| EventCode | string | Código reduzido que representa o evento (Ex.: “ODR”) | Yes |
| EventFullCode | string | Descrição completa do evento (Ex.: “ORDER_DETAILS_REQUESTED”) | Yes |
Request body
{ "OrderId": "cfa5ed42-9bab-4f5e-bac3-83b9a7b3a738", "EventCode": "ODR", "EventFull": "Pedido finalizado"}
Response Body Parameters
| Name | Type | Description | Required |
|---|---|---|---|
| id | string | Identificador único do evento | Yes |
| orderId | string | Identificador único do pedido ao qual o evento está relacionado | Yes |
| createdAt | string (DateTime) | Data e hora de criação do evento no formato UTC ISO 8601 | Yes |
| fullCode | string | Descrição completa do status ou evento (Ex.: “ORDER_DETAILS_REQUESTED”) | Yes |
| code | string | Código reduzido que representa o status ou evento (Ex.: “ODR”) | Yes |
Response body:
{"id": "1e97972c-e915-0h0b-b8f4-43dc1401580f","orderId": "e7c5fdbb-a3e1-0h0b-a22d-a99c734ef491","createdAt": "2025-05-15T20:30:56.5315412Z","fullCode": "ORDER_DETAILS_REQUESTED","code": "ODR"}
Ao receber esse evento no polling, o Consumer deve, então, chamar o endpoint definido na API do parceiro, enviando todos os detalhes do pedido por meio de uma requisição POST
| Name | Type | Description | Required |
|---|---|---|---|
| Id | string | ID único do pedido | Yes |
| Type | string | Tipo do pedido (“DELIVERY”, “INDOOR”, etc.) | Yes |
| DisplayId | string | Número do pedido visível ao cliente | Yes |
| SourceAppId | string | ID da aplicação origem | No |
| SalesChannel | string | Canal de venda (“DeliveryHub”, “Desktop”, etc.) | No |
| VirtualBrand | string | Nome da marca ou unidade virtual | No |
| CreatedAt | datetime | Data/hora de criação do pedido | Yes |
| LastEvent | string | Último evento do pedido (“CREATED”, etc.) | No |
| OrderTiming | string | Tipo de entrega (“INSTANT”, “SCHEDULED”) | Yes |
| PreparationStartDateTime | datetime | Data/hora de início do preparo | Yes |
| Merchant | object | Informação do Merchant | Yes |
| Itens | array de object | Produtos e informações | Yes |
| OtherFees | object | Informações relacionadas ao cliente | No |
| Total | object | Conjunto de campos com a soma dos valores descritos anteriormente na ordem | Yes |
| Payments | object | Toda a descrição do pagamento, como métodos, pré-pagamentos, troco, etc | Yes |
| Customer | object | Informações para pedidos agendados | No |
| OrderPriority | string | Prioridade do pedido (“PRIORITY1”, etc.) | No |
| Delivery | object | Informações para pedidos de ENTREGA | No |
| ExtraInfo | string | Informações adicionais ou observações | No |
- Merchant
| Name | Type | Description | Required |
|---|---|---|---|
| Id | string | ID do estabelecimento | Yes |
| Name | string | Nome do estabelecimento | Yes |
- Itens
| Name | Type | Description | Required |
|---|---|---|---|
| Id | string | ID do item (contém informações internas serializadas) | Yes |
| Index | integer | Ordem do item | No |
| Name | string | Nome do produto | Yes |
| ExternalCode | string | Código interno do produto | Yes |
| Quantity | number | Quantidade | Yes |
| SpecialInstructions | string | Observações | No |
| UnitPrice | object | Preço unitário | Yes |
| UnitPrice: Value | Number | Valor unitário | Yes |
| UnitPrice: Currency | String | Código de moeda | Yes |
| OptionsPrice | object | Preço dos opcionais | No |
| OptionsPrice: Value | Number | Valor | Yes |
| OptionsPrice: Currency | String | Código da moeda | Yes |
| SubtotalPrice | object | Subtotal (produto sem opcionais) | No |
| SubtotalPrice: Value | Number | Valor | Yes |
| SubtotalPrice: Currency | String | Código da moeda | Yes |
| TotalPrice | object | Total (produto + opcionais) | Yes |
| TotalPrice: Value | Number | Valor | Yes |
| TotalPrice: Currency | String | Código da moeda | Yes |
| Indoor | object | Propriedades relacionadas ao item para quando o pedido é do tipoINDOOR | No |
| Options | array | Lista de complementos ou divisões do produto. Segue mesma linha de raciocínio dos Itens | No |
- Otherfees
| Name | Type | Description | Required |
|---|---|---|---|
| Name | string | Nome da taxa (ex.: “TaxaEntrega”) | Yes |
| Type | string | Tipo da taxa (“DELIVERY_FEE”, etc.) | Yes |
| Price | object | Valor da taxa | Yes |
| Price: Value | number | Valor | Yes |
| Price: Currency | string | Código de moeda | Yes |
| ReceivedBy | string | Quem recebe a taxa (“MERCHANT”, “PARTNER”) | Yes |
| receiverDocument | string | Documento | No |
| observation | string | Algum comentário | No |
- Total
| Name | Type | Description | Required |
|---|---|---|---|
| ItemsPrice | object | Soma dos itens | Yes |
| OtherFees | object | Soma das taxas | Yes |
| Discount | object | Total de descontos | Yes |
| OrderAmount | object | Valor total do pedido | Yes |
- Payments
| Name | Type | Description | Required |
|---|---|---|---|
| Prepaid | number | Valor já pago | Yes |
| Pending | number | Valor pendente | Yes |
| Methods | array | Detalhes dos métodos de pagamento | Yes |
| Methods: value | number | Valor do preço | Yes |
| Methods: currency | string | O código de moeda | Yes |
| Methods: type | string | Enum: “PREPAID” “PENDING” “PREPAID” se o pagamento foi feito através de alguma plataforma, ou PENDING se será pago na entrega ou em dinheiro, por exemplo. | Yes |
| Methods: method | string | Enum: "CREDIT" "DEBIT" "MEAL_VOUCHER" "FOOD_VOUCHER" "DIGITAL_WALLET" "PIX" "CASH" "CREDIT_DEBIT" "COUPON" "REDEEM" "PREPAID_REDEEM" "OTHER” | Yes |
| Methods: brand | string | Enum:"VISA" "MASTERCARD" "DINERS" "AMEX" "HIPERCARD" "ELO" "AURA" "DISCOVER" "VR_BENEFICIOS" "SODEXO" "TICKET" "GOOD_CARD" "BANESCARD" "SOROCARD" "POLICARD" "VALECARD" "AGICARD" "JCB" "CREDSYSTEM" "CABAL" "GREEN_CARD" "VEROCHEQUE""AVISTA" "OTHER” | No |
| Methods: methodInfo | string | Informações adicionais sobre o método de pagamento. Podem ser usadas para indicar informações úteis sobre o método de pagamento escolhido, como o nome da carteira ou um número de autorização | No |
| Methods: transaction | object | Detalhes de autorização e identificação intermediária para transações de cartão de crédito e/ou subsídios | No |
| Transaction: authorizationCode | string | Número de autorização de transação de cartão de crédito e/ou subsídio | No |
| Transaction: acquirerDocument | string | Documento do Intermediário de Transação (agência, plataforma de entrega, marketplace e similares) de serviços e negócios | No |
| Methods: changeFor | number | Número < decimal > Indica o total que será pago em dinheiro pelo cliente e que deve ser considerado para o cálculo do troco | No |
- Customer
| Name | Type | Description | Required |
|---|---|---|---|
| Id | string | ID do cliente | Yes |
| Name | string | Nome | Yes |
| Phone | string | Telefone | Yes |
| Phone: Number | string | Numero | Yes |
| Phone: extension | string | – | No |
| OrdersCountOnMerchant | int | Total de pedidos do cliente no merchant | Yes |
| documentNumber | string | Documento do cliente | No |
| string | No |
- Delivery
| Name | Type | Description | Required |
|---|---|---|---|
| DeliveredBy | string | Quem realiza a entrega | Yes |
| EstimatedDeliveryDateTime | datetime | Previsão de entrega | Yes |
| DeliveryAddress | object | Endereço de entrega | Yes |
| deliveryDateTime | string | Data de entrega | No |
| pickupCode | string | Ele fornece ao comerciante um código para que o entregador possa retirar o pedido. | No |
Request Body:
{ "Id": "537976a8-0b48-426c-8369-3d5adf7dd5fe", "Type": "DELIVERY", "DisplayId": "32", "SourceAppId": "200971", "SalesChannel": "DeliveryHub", "VirtualBrand": "Teste", "CreatedAt": "2025-05-22T18:04:39Z", "LastEvent": "CREATED", "OrderTiming": "INSTANT", "PreparationStartDateTime": "2025-05-22T18:05:04Z", "Merchant": { "Id": "2eff44c8-ff06-4507-8233-e3f72c4e59af", "Name": "N/D" }, "Items": [ { "Id":"{\"ItemID\":739463,\"ParentItemID\":null,\"ItemSource\":\"DeliveryHub\",\"Type\":\"Product\"}", "Index": 0, "Name": "Pizza BACALHAU BROTO", "ExternalCode": "112", "Unit": "UN", "Ean": null, "Quantity": 2, "SpecialInstructions": "Observação produto principal", "UnitPrice": { "Value": 22, "Currency": "BRL" }, "OriginalPrice": null, "ScalePriceApplied": false, "OptionsPrice": { "Value": 0, "Currency": "BRL" }, "SubtotalPrice": { "Value": 44, "Currency": "BRL" }, "TotalPrice": { "Value": 44, "Currency": "BRL" }, "Indoor": null, "Options": [], "ConsumerItemInfo": null }, { "Id":"{\"ItemID\":739464,\"ParentItemID\":null,\"ItemSource\":\"DeliveryHub\",\"Type\":\"Product\"}", "Index": 1, "Name": "Pizza AZEITONA GRANDE", "ExternalCode": "107", "Unit": "UN", "Ean": null, "Quantity": 1, "SpecialInstructions": "Sim, quero ketchup, Maionese Temperada, Ao Ponto, Observação produto principal", "UnitPrice": { "Value": 30, "Currency": "BRL" }, "OriginalPrice": null, "ScalePriceApplied": false, "OptionsPrice": { "Value": 7.5, "Currency": "BRL" }, "SubtotalPrice": { "Value": 30, "Currency": "BRL" }, "TotalPrice": { "Value": 37.5, "Currency": "BRL" }, "Indoor": null, "Options": [ { "Index": 0, "Id":"{\"ItemID\":739465,\"ParentItemID\":739464,\"ItemSource\":\"DeliveryHub\",\"Type\":\"Complement\"}", "Name": "* Excluído * Borda cheddar", "ExternalCode": "7", "Unit": "UN", "Ean": null, "Quantity": 2, "UnitPrice": { "Value": 3.5, "Currency": "BRL" }, "OriginalPrice": null, "SubtotalPrice": { "Value": 7, "Currency": "BRL" }, "TotalPrice": { "Value": 7, "Currency": "BRL" }, "SpecialInstructions": "", "ConsumerItemInfo": null }, { "Index": 1, "Id":"{\"ItemID\":739466,\"ParentItemID\":739464,\"ItemSource\":\"DeliveryHub\",\"Type\":\"Product\"}", "Name": "Pizza CALABRESA ESPECIAL BROTO", "ExternalCode": "142", "Unit": "UN", "Ean": null, "Quantity": 1, "UnitPrice": { "Value": 0.5, "Currency": "BRL" }, "OriginalPrice": null, "SubtotalPrice": { "Value": 0.5, "Currency": "BRL" }, "TotalPrice": { "Value": 0.5, "Currency": "BRL" }, "SpecialInstructions": "", "ConsumerItemInfo": null } ], "ConsumerItemInfo": null }, { "Id":"{\"ItemID\":739467,\"ParentItemID\":null,\"ItemSource\":\"DeliveryHub\",\"Type\":\"Product\"}", "Index": 2, "Name": "Pizza BACON GRANDE", "ExternalCode": "110", "Unit": "UN", "Ean": null, "Quantity": 1, "SpecialInstructions": "Maionese Temperada, Ao Ponto, Observação produto principal", "UnitPrice": { "Value": 35, "Currency": "BRL" }, "OriginalPrice": null, "ScalePriceApplied": false, "OptionsPrice": { "Value": 34.5, "Currency": "BRL" }, "SubtotalPrice": { "Value": 35, "Currency": "BRL" }, "TotalPrice": { "Value": 69.5, "Currency": "BRL" }, "Indoor": null, "Options": [ { "Index": 2, "Id":"{\"ItemID\":739468,\"ParentItemID\":739467,\"ItemSource\":\"DeliveryHub\",\"Type\":\"Complement\"}", "Name": "* Excluído * Borda cheddar", "ExternalCode": "7", "Unit": "UN", "Ean": null, "Quantity": 2, "UnitPrice": { "Value": 3.5, "Currency": "BRL" }, "OriginalPrice": null, "SubtotalPrice": { "Value": 7, "Currency": "BRL" }, "TotalPrice": { "Value": 7, "Currency": "BRL" }, "SpecialInstructions": "", "ConsumerItemInfo": null }, { "Index": 3, "Id":"{\"ItemID\":739469,\"ParentItemID\":739467,\"ItemSource\":\"DeliveryHub\",\"Type\":\"Product\"}", "Name": "Pizza CALABRESA ESPECIAL GRANDE", "ExternalCode": "143", "Unit": "UN", "Ean": null, "Quantity": 1, "UnitPrice": { "Value": 0.5, "Currency": "BRL" }, "OriginalPrice": null, "SubtotalPrice": { "Value": 0.5, "Currency": "BRL" }, "TotalPrice": { "Value": 0.5, "Currency": "BRL" }, "SpecialInstructions": "", "ConsumerItemInfo": null }, { "Index": 4, "Id":"{\"ItemID\":739470,\"ParentItemID\":739467,\"ItemSource\":\"DeliveryHub\",\"Type\":\"Product\"}", "Name": "Pizza BACALHAU MEDIA", "ExternalCode": "114", "Unit": "UN", "Ean": null, "Quantity": 1, "UnitPrice": { "Value": 5, "Currency": "BRL" }, "OriginalPrice": null, "SubtotalPrice": { "Value": 5, "Currency": "BRL" }, "TotalPrice": { "Value": 5, "Currency": "BRL" }, "SpecialInstructions": "Copo com limão e gelo", "ConsumerItemInfo": null }, { "Index": 5, "Id": "{\"ItemID\":739471,\"ParentItemID\":739467,\"ItemSource\":\"DeliveryHub\",\"Type\":\"Product\"}", "Name": "Pizza BACALHAU GRANDE", "ExternalCode": "113", "Unit": "UN", "Ean": null, "Quantity": 1, "UnitPrice": { "Value": 15, "Currency": "BRL" }, "OriginalPrice": null, "SubtotalPrice": { "Value": 15, "Currency": "BRL" }, "TotalPrice": { "Value": 22, "Currency": "BRL" }, "SpecialInstructions": "Dividir a porção em dois", "ConsumerItemInfo": null }, { "Index": 6, "Id":"{\"ItemID\":739472,\"ParentItemID\":739471,\"ItemSource\":\"DeliveryHub\",\"Type\":\"Complement\"}", "Name": "* Excluído * Borda cheddar", "ExternalCode": "7", "Unit": "UN", "Ean": null, "Quantity": 1, "UnitPrice": { "Value": 7, "Currency": "BRL" }, "OriginalPrice": null, "SubtotalPrice": { "Value": 7, "Currency": "BRL" }, "TotalPrice": { "Value": 7, "Currency": "BRL" }, "SpecialInstructions": "", "ConsumerItemInfo": null } ], "ConsumerItemInfo": null } ], "OtherFees": [ { "Name": "TaxaEntrega", "Type": "DELIVERY_FEE", "ReceivedBy": "MERCHANT", "ReceiverDocument": null, "Price": { "Value": 3.99, "Currency": "BRL" }, "Observation": null } ], "Discounts": [], "Total": { "ItemsPrice": { "Value": 151, "Currency": "BRL" }, "OtherFees": { "Value": 3.99, "Currency": "BRL" }, "Discount": { "Value": 0, "Currency": "BRL" }, "OrderAmount": { "Value": 154.99, "Currency": "BRL" } }, "Payments": { "Prepaid": 0, "Pending": 103.02, "Methods": [ { "Value": 51.97, "Currency": "BRL", "Type": "PREPAID", "Method": "CREDIT", "Brand": "OTHER", "MethodInfo": "American Express", "Transaction": { "AuthorizationCode": null, "AcquirerDocument": "228908" }, "ChangeFor": 0 } ] }, "TaxInvoice": null, "Customer": { "Id": "910a258a-bcd3-4564-a62b-d29c61c94985", "Name": "PEDIDO DE TESTE - Fulano de Tal", "DocumentNumber": null, "Phone": { "Number": "N/D", "Extension": null }, "Email": null, "OrdersCountOnMerchant": 0 }, "Schedule": null, "OrderPriority": "PRIORITY1", "Delivery": { "DeliveredBy": "MERCHANT", "DeliveryAddress": { "Country": "BR", "State": "XX", "City": "TESTE", "District": "TESTE", "Street": "Rua TESTE", "Number": "999999", "Complement": "Complemento TESTE", "Reference": "TESTE", "FormattedAddress": "Rua TESTE, 999999, Complemento TESTE, Bairro TESTE - TESTE, XX - Brazil", "PostalCode": "99999999", "Coordinates": { "Latitude": 0, "Longitude": 0 } }, "EstimatedDeliveryDateTime": "2025-05-22T18:03:55Z", "DeliveryDateTime": null, "PickupCode": null }, "Takeout": null, "Indoor": null, "SendPreparing": false, "SendDelivered": false, "SendPickedUp": false, "SendTracking": false, "ExtraInfo": "0800 012 3456 ID: 54639728 | Teste de Observação Delivery"}
Response Body Parameters
| Name | Type | Description | Required |
|---|---|---|---|
| statusCode | int | Código de status da resposta da API (0 normalmente indica sucesso) | Yes |
| reasonPhrase | string | Frase de motivo ou descrição adicional sobre o status (pode ser nulo) | No |
Response Body:
{ "statusCode": 0, "reasonPhrase": "fb82376e-db8c-4bca-85ec-020322e9b1b4 enviado com sucesso."}
Endpoint de alteração de status do pedido
Após obter os detalhes do pedido e exibir as informações na tela, o Consumer permite que o usuário tome uma decisão: confirmar ou cancelar o pedido.
Depois que o usuário decide, o Consumer deve enviar a alteração de status correspondente para a API do parceiro.
Os status possíveis incluem:
- Confirmado: O pedido foi confirmado pelo usuário.
- Cancelado: O pedido foi cancelado pelo usuário.
- Pronto para Retirada: O pedido está pronto para ser retirado pelo cliente.
- Saiu para Entrega: O pedido foi despachado para entrega no endereço do cliente.
- Finalizado: O pedido foi concluído com sucesso.
Esses status são enviados para a API do parceiro para refletir o progresso do pedido em tempo real.
Request Path Parameter
| Name | Type | Description | Required |
|---|---|---|---|
| orderId | string | ID do pedido | Yes |
| status | string | Status do pedido | Yes |
| justification | string | Justificativa da alteração | No |
Request body
{ "orderId": "cfa5ed42-9bab-4f5e-bac3-83b9a7b3a738", "status": "CONCLUDED", "justification": "Pedido finalizado"}
Response Body Parameters
| Name | Type | Description | Required |
|---|---|---|---|
| statusCode | integer | Código de status da operação (ex.: 0 para sucesso) | Yes |
| reasonPhrase | string | Mensagem descritiva da operação | No |
Response body
{ "statusCode": 0, "reasonPhrase": "cfa5ed42-9bab-4f5e-bac3-83b9a7b3a738 alterado para 'CONCLUDED': Pedido finalizado."}
Integração dos produtos do pedido
Para garantir uma integração correta dos itens do pedido no Consumer, o primeiro passo essencial é assegurar o preenchimento dos códigos de PDV na plataforma do parceiro.
A API do parceiro deve retornar o código PDV de cada produto ou complemento do pedido no “externalCode“, permitindo que o Consumer identifique claramente todos os itens contidos nele.
O Consumer simplifica esse processo, exibindo os códigos de maneira intuitiva e acessível, facilitando a integração e a gestão dos itens.
Para visualizar o código PDV de cada produto, acesse o menu:
PRODUTOS → PRODUTOS
Para produtos por tamanho marque a opção “Detalhar todos os tamanhos
Nessa tela é possível identificar o código PDV de todos os produtos, e caso necessário exportar para um arquivo “.xls”.
Para visualizar o código PDV de cada complemento, acesse o menu:
PRODUTOS → COMPLEMENTOS
Também é possível visualizar e exportar toda a lista de códigos acessando o menu:
APPS → Pedidos Online → Exportar Cardápio
A seguir, apresentamos alguns exemplos com diferentes tipos de produtos:
Produto simples
{ ... "items": [ { "unitPrice": 22, "quantity": 2, "externalCode": "112", "totalPrice": 44, "index": 1, "unit": "UN", "ean": null, "price": 44, "observations": "Observação produto principal", "imageUrl": "https://seusite.com.br/image/e078d2e1-0af0-49c3-ba0d-ea4effffbd54/202305121137_XIHJ_i.jpg", "name": "Alabama Apimentado", "options": null, "id": "31223e2c-c8a4-4018-b7fc-e765b9efaf4e", "uniqueId": "110d3f32-0359-4ea5-bc7e-05b0ef72e513", "optionsPrice": 0, "addition": 0, "scalePrices": null } ] ...}
Produto com complementos e observações como opções
{ ... "items": [ { "unitPrice": 30, "quantity": 1, "externalCode": "107", "totalPrice": 30, "index": 2, "unit": "UN", "ean": null, "price": 30, "observations": "Observação produto principal", "imageUrl": "https://seusite.com.br/image/e078d2e1-0af0-49c3-ba0d-ea4effffbd54/202305121137_XIHJ_i.jpg", "name": "Alabama Filé (exemplo perguntas)", "options": [ { "unitPrice": 0, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "WO", "price": 0, "name": "Ao Ponto", "index": 0, "id": "7ff678cc-7ef0-45b2-b21f-7e90e0b068aa", "addition": 0 }, { "unitPrice": 0, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "WO", "price": 0, "name": "Maionese Temperada", "index": 0, "id": "dcf7576c-bcc1-431b-bd3b-10594fbde0b1", "addition": 0 }, { "unitPrice": 0, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "WO", "price": 0, "name": "Sim, quero ketchup", "index": 0, "id": "1b9364ec-dbe6-4c48-a2fb-f4325307a06c", "addition": 0 }, { "unitPrice": 3.5, "unit": "UN", "ean": null, "quantity": 2, "externalCode": "7", "price": 3.5, "name": "Bacon", "index": 0, "id": "d7b6ebff-c40f-44e8-9834-05a534457c71", "addition": 0 }, { "unitPrice": 0.5, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "142", "price": 0.5, "name": "Alface", "index": 0, "id": "b99db576-170e-49f4-9975-e5f30901c327", "addition": 0 } ], "id": "ae64778e-8315-40e9-890b-30a1003f785b", "uniqueId": "86cc8c5e-8d04-43c3-9987-9be1171e59fe", "optionsPrice": 36, "addition": 0, "scalePrices": null } ] ...}
Produto com complementos, observações e outros produtos como opções
{ ... "items": [ { "unitPrice": 35, "quantity": 1, "externalCode": "110", "totalPrice": 35, "index": 2, "unit": "UN", "ean": null, "price": 35, "observations": "Observação produto principal", "imageUrl": "https://seusite.com.br/image/e078d2e1-0af0-49c3-ba0d-ea4effffbd54/202305121137_XIHJ_i.jpg", "name": "Alabama Bacon Duplo", "options": [ { "unitPrice": 0, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "WO", "price": 0, "name": "Ao Ponto", "index": 0, "id": "784f1edc-c54d-404f-aade-3dd92131695a", "addition": 0 }, { "unitPrice": 0, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "WO", "price": 0, "name": "Maionese Temperada", "index": 0, "id": "31b31dc1-8c1b-4564-afef-e820de4acea8", "addition": 0 }, { "unitPrice": 3.5, "unit": "UN", "ean": null, "quantity": 2, "externalCode": "7", "price": 3.5, "name": "Bacon", "index": 0, "id": "3722d2f3-d15e-4388-a0ab-01ef4a99ae35", "addition": 0 }, { "unitPrice": 0.5, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "143", "price": 0.5, "name": "Cebola", "index": 0, "id": "3cb78b64-8914-4338-82a9-60a2e9d01598", "addition": 0 }, { "unitPrice": 5, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "114", "price": 5, "name": "Coca-Cola 350ml", "index": 0, "id": "08ec8e17-3e6c-4a55-9287-27e02951fa67", "addition": 0 }, { "unitPrice": 0, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "WO", "price": 0, "name": "Copo com limão e gelo", "index": 0, "id": "c0fd1a19-534b-47b7-996c-4f595f427b61", "addition": 0 }, { "unitPrice": 15, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "113", "price": 15, "name": "Batata Frita Tradicional", "index": 0, "id": "29579ed7-6986-4b63-8311-474f6efa597e", "addition": 0 }, { "unitPrice": 0, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "WO", "price": 0, "name": "Dividir a porção em dois", "index": 0, "id": "700ec387-9163-4103-a3e2-3e47e1c3340f", "addition": 0 }, { "unitPrice": 7, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "7", "price": 7, "name": "Bacon", "index": 0, "id": "39c7cf96-a2fb-4ff5-a451-1b5082928b03", "addition": 0 } ], "id": "bf052fec-8f29-42c0-a863-d711c94a2dfa", "uniqueId": "2d693a11-daa6-472e-a6bf-2a1b8597f0b9", "optionsPrice": 36, "addition": 0, "scalePrices": null } ] ...}
Produto por tamanho com múltiplos sabores e com complementos
{ ... "items": [ { "unitPrice": 0, "quantity": 1, "externalCode": "T8", "totalPrice": 36, "index": 2, "unit": "UN", "ean": null, "price": 0, "observations": "Observação produto principal", "imageUrl": "https://seusite.com.br/image/e078d2e1-0af0-49c3-ba0d-ea4effffbd54/202305121137_XIHJ_i.jpg", "name": "Pizza Grande", "options": [ { "unitPrice": 18, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "55", "price": 18, "name": "1/2 Calabresa", "index": 3, "id": "4727afa0-9542-4474-9aac-32bb4a353305", "addition": 0.5 }, { "unitPrice": 17.5, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "133", "price": 18, "name": "1/2 Baiana", "index": 4, "id": "f3acf9bd-4529-4d5d-b8e3-6cbb90d85556", "addition": 0.5 }, { "unitPrice": 5, "unit": "UN", "ean": null, "quantity": 1, "externalCode": "4", "price": 5, "name": "Borda Catupiry", "index": 0, "id": "7914333e-bf6c-4a70-a7eb-739c6306c061", "addition": 0 } ], "id": "46e8d008-21c9-4e3b-9722-13335abecbd7", "uniqueId": "58a97023-5c85-4136-b1ac-ca6c6235583a", "optionsPrice": 36, "addition": 0, "scalePrices": null } ] ...}
Configuração no Consumer
Após a conclusão do desenvolvimento e da implementação dos endpoints por parte da empresa parceira, é necessário proceder com a configuração no Consumer. Para isso, solicitamos que o parceiro compartilhe o token de acesso e as URLs dos endpoints com o estabelecimento.
Com essas informações, basta seguir as orientações abaixo para ativar a integração.
Acesse o menu:
APPS → Pedidos Online → API do parceiro
Preencha todos os campos com as informações fornecidas pela empresa parceira, seguindo o exemplo abaixo:
Atenção: preencha o campo “token” com o token fornecido pelo parceiro para garantir a correta identificação da loja e uma integração segura e eficiente com a API do parceiro.
Após preencher e validar todas as informações, a opção para ativar a integração na fila de pedidos online estará disponível.
Acesse o menu:
Principal→ Fila de Pedidos
Ative a fila de pedidos e o Consumer estará pronto para receber os pedidos do parceiro.
Após ativar a fila de pedidos online, os pedidos do parceiro serão integrados e exibidos para atendimento.
Para pedidos do tipo delivery, após atender o pedido ele será listado na tela de pedidos delivery
Para enviar as alterações de status dos pedidos delivery para a API do parceiro, basta selecionar o status desejado na tela do pedido, após isso o Consumer enviará automaticamente a atualização para a API do parceiro.
Pedidos para Mesas e Comandas
A integração também permite o envio de pedidos para mesas e comandas, oferecendo maior flexibilidade no gerenciamento de pedidos. Com esse tipo de pedido, é possível adicionar diferentes itens a uma mesa ou comanda em momentos distintos, conforme o cliente faz novos pedidos.
Essa funcionalidade permite um fluxo contínuo de pedidos até que o cliente decida encerrar sua conta e efetuar o pagamento.
Essa abordagem é ideal para estabelecimentos onde os clientes permanecem por períodos prolongados e fazem pedidos de forma gradual, como em refeições completas, encontros sociais, ou eventos.
Quando um pedido integrado for recebido, ele será exibido na fila de pedidos para atendimento. Após ser atendido, a mesa correspondente será aberta com os itens registrados.
Caso a mesa já esteja aberta, os itens enviados serão adicionados à mesa existente.
Para que o Consumer identifique corretamente os pedidos como mesas e comandas, o endpoint de detalhes do pedido deve retornar um código 200, juntamente com todas as informações detalhadas do pedido.
Exemplo:
A estrutura geral mantém o mesmo formato de um pedido de delivery. No entanto, é necessário alterar o valor de “orderType” para “INDOOR” e preencher as informações no campo “indoor”.
Exemplos:
{ ... "item": { ... "orderType": "INDOOR", ... } ...}
Preenchimento das informações em “indoor”:
{ "item": { ... "indoor": { "mode": "TABLE", "deliveryDateTime": "2024-08-27T15:37:05.0380282Z", "table": "1", "observations": "" }, ... }, ...}
Conclusão
A integração com o sistema Consumer oferece uma maneira eficiente e automatizada de gerenciar pedidos provenientes de parceiros, melhorando a comunicação e a experiência geral de nossos clientes. Ao seguir as diretrizes e especificações apresentadas neste manual, os parceiros poderão garantir que seus pedidos sejam corretamente incorporados e gerenciados no sistema Consumer.
Lembramos que é essencial testar todos os endpoints e fluxos de integração para assegurar a precisão dos dados e o funcionamento adequado dos processos de pedido e atualização de status.
Em caso de dúvidas ou necessidade de suporte durante a implementação, entre em contato com a equipe de suporte técnico do Consumer, que está à disposição para auxiliar.
E-mail para contato: ajuda@programaconsumer.com.br
Com uma integração bem-sucedida, os parceiros terão acesso a uma solução robusta e confiável, permitindo uma melhor gestão de pedidos e uma experiência aprimorada para seus clientes.
Para facilitar o entendimento do desenvolvedor interessado na implementação, disponibilizamos abaixo um código-fonte de exemplo para download.
Ficou com dúvida?
Se você seguiu os passos acima e ainda tem alguma dúvida, nossa equipe está pronta para te ajudar.
Você também pode nos contatar pelos canais:
- Chat disponível na Central de Ajuda
- WhatsApp direto com nossa equipe de especialistas
Estamos aqui para garantir que você aproveite ao máximo o Consumer!