Obrigado pelo interesse em desenvolver com a nossa API de integrações que foi desenvolvida com o intuito ajudar a facilitar o dia a dia operação dos estabelecimentos parceiros, que muitas vezes precisam de uma automação nas suas operações para evitar possíveis erros humanos que podem acontecer por um grande fluxo ou quaisquer motivos operacionais.
Então vamos começar?
Modelos
Nesse capítulo veremos todos os Models da nossa API que são a representação dos nossos recursos. Basicamente, iremos trabalhar com dois modelos: Event e Order.
Event
Como o nome já diz, representa um Evento no Supermenu, ou seja, quaisquer ocorrências dentro do sistema, como se fosse um log de tudo que acontecer. Segue abaixo uma representação em JSON do shape do modelo Event:
[
{
"code": "string", // *1 ex: PENDING_APPROVAL, APPROVED, DELIVERED etc.
"correlationId": "string", // ex : 784516516548484
"createdAt": "2018-09-05T16:43:52.264Z",
"integrated": "boolean", //true ou false
"id": "string" // 51sdw15454fwf1515
}
]
//// *1 Os códigos para o code do event são:
//
*1: Os valores para o atributo 'code' são: 'PENDING_APPROVAL', 'APPROVED', 'WAITING_FOR_DELIVERY', 'OUT_FOR_DELIVERY', 'DELIVERED', 'REFUSED' e 'FINISHED'
Vamos explicar o que cada um desses codes significam:
PENDING_APPROVAL: Significa que o pedido foi feito pelo cliente e foi 'colocado' no sistema;
APPROVED: Significa que o pedido foi confirmado e aceito pelo estabelecimento;
WAITING_FOR_DELIVERY: Esse status é exclusivo para quem está com sua integração com o motoboy.com ativada. Ela indica que o motoboy foi solicitado e que o mesmo está para chegar para fazer a entrega;
OUT_FOR_DELIVERY: Significa que o pedido já foi mandado para entrega;
DELIVERED: Significa que o pedido foi entregue com sucesso;
REFUSED: Significa que o pedido foi rejeitado pelo estabelecimento (lembrando que isso não apaga o pedido);
CANCELLED: Significa que o pedido foi cancelado;
Order
Order representa o pedido feito no app, segue abaixo a estrutura do Order:
{
"id": "Id de referencia interno",
"createdAt": "Timestamp do pedido",
"type": "Tipo do pedido('DELIVERY', 'ESTABLISHMENT' ou 'TOGO')",
"merchant": {
"id": "Identificador unico do estabelecimento⁎",
"name": "Nome do estabelecimento",
"phones": [
"Telefone do estabelecimento 1",
"Telefone do estabelecimento 2 ....."
]
"address": {
"formattedAddress": "Endereço formatado",
"country": "Pais",
"state": "Estado",
"city": "Cidade",
"neighborhood": "Bairro",
"streetName": "Endereço (Tipo logradouro + Logradouro)",
"streetNumber": "Numero",
"postalCode": "CEP"
}
},
"payment": { //Forma de pagamento⁎⁎
"kind":"Tipo de pagamento",
"label":"Nomde do tipo de pagamento",
"legend":"Bandeira e final do cartão",
"cvv":"Código de verificação"
},
"customer": {
"id": "Id do cliente",
"name": "Nome do cliente",
"taxPayerIdentificationNumber": "CPF/CNPJ do cliente ",
"phone": "Telefone do cliente",
"email": "Email do cliente"
},
"items": [
{
"reference": "ID do item",
"name": "Nome do item",
"quantity": "Quantidade",
"price": "Preço",
"subItemsPrice": "Preço dos subitens",
"totalPrice": "Preço total",
"externalCode": "Código do e-PDV",
"observations": "Observação do item",
"subItems": [
{
"reference": "ID do subItem",
"name": "Nome do item",
"quantity": "Quantidade",
"price": "Preço",
"totalPrice": "Preço total",
"externalCode": "Código do e-PDV"
}
]
},
{
"reference": "ID do item",
"name": "Nome do item",
"quantity": "Quantidade",
"price": "Preço",
"subItemsPrice": "Preço dos subitens",
"totalPrice": "Preço total",
"observations": "Observação do item",
"subItems": [
{
"reference": "ID do subItem",
"name": "Nome do item",
"quantity": "Quantidade",
"price": "Preço",
"totalPrice": "Preço total",
"externalCode": "Código e-PDV"
}
]
},
{
"reference": "ID do item",
"name": "Nome do item",
"quantity": "Quantidade",
"price": "Preço",
"subItemsPrice": "Preço dos subitens",
"totalPrice": "Preço total",
"externalCode": "Código do e-PDV",
"observations": "Observação do item"
}
],
"subTotal": "Total do pedido(Sem taxa de entrega)",
"totalPrice": "Total do pedido(Com taxa de entrega)",
"deliveryFee": "Taxa de entrega",
"changeFor": "Troco para...",
"discount": "Desconto"
"deliveryAddress": {
"formattedAddress": "Endereço completo do cliente",
"country": "Pais",
"state": "Estado",
"city": "Cidade",
"coordinates": {
"latitude": "Latitude do endereço",
"longitude": "Longitude do endereço"
},
"neighborhood": "Bairro",
"streetName": "Endereço(Tipo logradouro + Logradouro)",
"streetNumber": "Numero",
"postalCode": "CEP",
"reference": "Referência",
"complement": "Complemento do endereço"
}
}
Caso tenha ficado alguma dúvida, não se preocupe, segue abaixo um exemplo pra ajudar no esclarecimento:
{
"id": "ff80808161091d9601610adffc211dbf", //Id de referencia interno
"createdAt": "2018-09-06T20:05:06.177Z", //Timestamp do pedido
"type": "DELIVERY", //Tipo do pedido("DELIVERY", "ESTABLISHMENT" ou "TOGO")
"merchant": {
"id": "10487", //Identificador unico do estabelecimento
"name": "Modelo Teste Food", //Nome do estabelecimento
"phones": [
"(99) 9-9999-9999", //Telefone do estabelecimento
]
"address": {
"formattedAddress": "R Teste - 123 - Bairro Teste", //Endereço formatado
"country": "BR", //Pais
"state": CE", //Estado
"city": "FORTALEZA", //Cidade
"neighborhood": "Bairro Teste", //Bairro
"streetName": "R Teste", //Endereço (Tipo logradouro + Logradouro)
"streetNumber": "123", //Numero
"postalCode": "12345678" //CEP
}
},
"payment": { //Forma de pagamento⁎⁎
"kind": "Delivery" //Tipo de pagamento
"label": "Cielo crédito" //Nomde do tipo de pagamento
"legend": "MasterCard ***********1234" //Bandeira e final do cartão
"cvv": "000 //Código de verificação
},
"customer": {
"id": "1751813", //Id do cliente
"name": "Supermenu Teste", //Nome do cliente
"taxPayerIdentificationNumber": "01234567890", //CPF/CNPJ do cliente
"phone": "(99) 9-9999-9999", //Telefone do estabelecimento
"email": "TESTEC@SUPERMENU.COM.BR" //Email do cliente
},
"items": [
{
"reference": "f80808161091d9601610adffc211
"name": "X-sanduba", //Nome do item
"quantity": 1, //Quantidade
"price": 10, //Preço
"subItemsPrice": 3, //Preço dos subitens
"totalPrice": 13, //Preço total
"discount": 0, //Desconto
"externalCode": "7", //Código do e-PDV,
"observations": "" //Observação do item
"subItems": [
{
"reference": "e647364731610adffc211
"name": "Bacon", //Nome do item
"quantity": 1, //Quantidade
"price": 3, //Preço
"totalPrice": 3, //Preço total
"discount": 0, //Desconto
"externalCode": "11" //Código do e-PDV
}
]
},
{
"reference": "f80808161091d9601610adffc211
"name": "Pastel de frango", //Nome do item
"quantity": 1, //Quantidade
"price": 10, //Preço
"subItemsPrice": 0, //Preço dos subitens
"totalPrice": 10, //Preço total
"discount": 0, //Desconto
"externalCode": "4", //Código do e-PDV
"observations": "SEM MILHO E BEM CAPRICHADO!" //Observação do item
}
],
"subTotal": 23, //Total do pedido(Sem taxa de entrega)
"totalPrice": 31, //Total do pedido(Com taxa de entrega)
"deliveryFee": 8, //Taxa de entrega,
"changeFor": null, //Não tem troco, pois a compra foi feita com cartão
"deliveryAddress": {
"formattedAddress": "R Teste - 456 - Bairro Teste", //Endereço formatado
"country": "BR", //Pais
"state": CE", //Estado
"city": "FORTALEZA", //Cidade
"coordinates": {
"latitude": -9.824359, //latitude do endereço
"longitude": -67.950572 //longitude do endereço
},
"neighborhood": "Bairro Teste", //Bairro
"streetName": "R Teste", //Endereço (Tipo logradouro + Logradouro)
"streetNumber": "456", //Numero
"postalCode": "12345678" //CEP
"reference": "Próximo do ginásio teste" //Referência
"complement": "APTO 111" //Complemento do endereço
}
}
Com isso concluímos a nossa seção de modelos, quaisquer dúvidas ou esclarecimentos, favor entrar em contato, teremos prazer em esclarecer suas questões.
Fluxo do sistema
Ao se fazer um novo pedido, um evento é automaticamente criado. Dentro do seu sistema, você poderá fazer as devidas alterações nos pedidos, e no caso de o status do pedido ser alterado, a nossa API irá criar um novo evento relacionado a esse pedido, com isso, evitamos possíveis problemas de sincronia, pois esses dois elementos caminham de forma independente e permitem um maior controle do seu negócio e passa muito mais segurança e transparência.
Quando o pedido é criado, um evento será criado com o status PENDING_APPROVAL na API, após isso, o estabelecimento terá duas opções principais: Aceitar ou Rejeitar. Caso o pedido seja aceito, será criado um evento com o status APPROVED, indicando que tudo está de acordo com as diretrizes do estabelecimento. Por outro lado, caso algo esteja errado, o estabelecimento poderá rejeitar o pedido, gerando assim um evento com o status REFUSED.
Depois que um pedido foi confirmado pelo estabelecimento, ele será preparado e enviado para o cliente. No momento em que ele for enviado para delivery e tiver em trânsito para o cliente, será criado na API um novo evento com status OUT_FOR_DELIVERY e posteriormente após o pedido ter sido entregue, será gerado um novo evento relacionado ao pedido com o status DELIVERED.
Nos casos em que o estabelecimento tenha a integração com o motoboy.com cadastrada e ativa, quando o pedido estiver pronto, o estabelecimento fará a solicitação do motoboy, o que irá gerar na API um evento com o status WAITING_FOR_DELIVERY, onde o motoboy pode ser cancelado (caso não se tenha nenhum motoboy alocado) o que irá retornar para o status anterior, no caso APPROVED, e no caso de o motoboy chegar se deslocar em direção ao destino da entrega, será gerado um evento do tipo OUT_FOR_DELIVERY conforme mencionado no parágrafo anterior.
Porém todos sabemos que imprevistos acontecem, nesse caso, teremos uma opção de evento com o status CANCELLED, para que tudo fique registrado mesmo em casos onde as coisas não saem como o planejado.
Pra ajudar a esclarecer quaisquer dúvidas que possam surgir, fizemos esse pequeno fluxo pra você:
Autenticação
As credenciais de acesso para nossa API(API_KEY) são geradas no dashboard do sistema e devem ser repassadas em todas as requisições.
Para gerar sua API_KEY basta você ir no dashboard do supermenu, clicar no menu integrações -> PDV, la você terá um painel para gerenciar suas aPI_KEY`s conforme desejar.
A API_KEY deve ser repassada no header authorization da requisição, conform o exemplo abaixo:
Javascript
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://api.supermenu.com.br/pdv/orders");
xhr.setRequestHeader("Authorization", "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9");
xhr.send(data);
cURL
curl -X GET \
https://api.supermenu.com.br/pdv/orders \
-H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9' \
HTTP
GET /pdv/orders HTTP/1.1
Host: https://api.supermenu.com.br
Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ
Endpoints
Agora iremos ver os endpoints para integração de delivery com o supermenu.
/pdv/orders/{id} - Buscar um pedido
GEThttps://api.supermenu.com.br/pdv/orders/{id}
Serve para buscar os dados de um pedido individualmente.
Path Parameters
Name
Type
Description
id
string
Id do pedido.
Headers
Name
Type
Description
authorization
string
API_KEY para autorizar a requisição
{
"id": "ff80808161091d9601610adffc211dbf", //Id de referencia interno
"createdAt": "2018-09-06T20:05:06.177Z", //Timestamp do pedido
"type": "DELIVERY", //Tipo do pedido("DELIVERY", "ESTABLISHMENT" ou "TOGO")
"merchant": {
"id": "10487", //Identificador unico do estabelecimento
"name": "Modelo Teste Food", //Nome do estabelecimento
"phones": [
"(99) 9-9999-9999", //Telefone do estabelecimento
]
"address": {
"formattedAddress": "R Teste - 123 - Bairro Teste", //Endereço formatado
"country": "BR", //Pais
"state": CE", //Estado
"city": "FORTALEZA", //Cidade
"neighborhood": "Bairro Teste", //Bairro
"streetName": "R Teste", //Endereço (Tipo logradouro + Logradouro)
"streetNumber": "123", //Numero
"postalCode": "12345678" //CEP
}
},
"payment": { //Forma de pagamento⁎⁎
"kind": "Delivery" //Tipo de pagamento
"label": "Cielo crédito" //Nomde do tipo de pagamento
"legend": "MasterCard ***********1234" //Bandeira e final do cartão
"cvv": "000 //Código de verificação
},
"customer": {
"id": "1751813", //Id do cliente
"name": "Supermenu Teste", //Nome do cliente
"taxPayerIdentificationNumber": "01234567890", //CPF/CNPJ do cliente
"phone": "(99) 9-9999-9999", //Telefone do estabelecimento
"email": "TESTEC@SUPERMENU.COM.BR" //Email do cliente
},
"items": [
{
"reference": "f80808161091d9601610adffc211
"name": "X-sanduba", //Nome do item
"quantity": 1, //Quantidade
"price": 10, //Preço
"subItemsPrice": 3, //Preço dos subitens
"totalPrice": 13, //Preço total
"discount": 0, //Desconto
"externalCode": "7", //Código do e-PDV,
"observations": "" //Observação do item
"subItems": [
{
"reference": "e647364731610adffc211
"name": "Bacon", //Nome do item
"quantity": 1, //Quantidade
"price": 3, //Preço
"totalPrice": 3, //Preço total
"discount": 0, //Desconto
"externalCode": "11" //Código do e-PDV
}
]
},
{
"reference": "f80808161091d9601610adffc211
"name": "Pastel de frango", //Nome do item
"quantity": 1, //Quantidade
"price": 10, //Preço
"subItemsPrice": 0, //Preço dos subitens
"totalPrice": 10, //Preço total
"discount": 0, //Desconto
"externalCode": "4", //Código do e-PDV
"observations": "SEM MILHO E BEM CAPRICHADO!" //Observação do item
}
],
"subTotal": 23, //Total do pedido(Sem taxa de entrega)
"totalPrice": 31, //Total do pedido(Com taxa de entrega)
"deliveryFee": 8, //Taxa de entrega
"deliveryAddress": {
"formattedAddress": "R Teste - 456 - Bairro Teste", //Endereço formatado
"country": "BR", //Pais
"state": CE", //Estado
"city": "FORTALEZA", //Cidade
"coordinates": {
"latitude": -9.824359, //latitude do endereço
"longitude": -67.950572 //longitude do endereço
},
"neighborhood": "Bairro Teste", //Bairro
"streetName": "R Teste", //Endereço (Tipo logradouro + Logradouro)
"streetNumber": "456", //Numero
"postalCode": "12345678" //CEP
"reference": "Próximo do ginásio teste" //Referência
"complement": "APTO 111" //Complemento do endereço
}
}
/pdv/events:polling - Buscar todos os pedidos não integrados
Após buscar os pedidos, esse endpoint informa pro supermenu quais os pedidos que foram integrados.
Os dados devem ser enviados em forma de array, diretamente no body (onde o type é JSON).
Para mudar o status de um pedido manualmente pelo seu PDV
Path Parameters
Name
Type
Description
id
string
Id do pedido
code
string
código desejado para o evento, os códigos suportados são: 'PENDING_APPROVAL', 'APPROVED', 'WAITING_FOR_DELIVERY', 'OUT_FOR_DELIVERY', 'DELIVERED', 'REFUSED' e 'FINISHED
