Pedidos v1

Primeira versão da API de pedidos

Os pedidos são acessados e manipulados através das rotas descritas abaixo.

Todo pedido deve ser aceito ou recusado em até 90 segundos, caso contrário, serão cancelados automaticamente.

É necessário que a automação também implemente os tratamentos para cancelamento de pedidos.

Os pedidos recusados pela integração ficam disponíveis para a loja no painel de pedidos da Goomer, para que a operação trate qualquer possível erro de forma manual, para posterior correção do problema.

Nesse painel exibimos a mensagem de erro retornada pela automação, portanto é recomendado que as mensagens sejam claras, curtas e em português.

Consulta de novos pedidos

Retorna a lista de pedidos pendentes disponíveis para a integração em um objeto do tipo OrderList. O retorno possui apenas os IDs dos pedidos para que sejam consultados pela rota de detalhes do pedido posteriormente.

Após a consulta, a automação deve tentar integrar cada pedido individualmente, e aceitar ou recusar o pedido utilizando as rotas Aceitar pedido ou Recusar pedido.

/orders/v1/list/new

GET https://api-integration.goomer.app/orders/v1/list/new

Headers

Name	Type	Description
x-api-key	string	Token de autenticação

200 Retorna a lista de IDs dos pedidos disponíveis

{
    "orders: [
        232,
        345,
        3892,
        23
    ]
}

401 Token inválido ou expirado. Atualize o token e tente novamente.

Unauthorized

Consulta de pedidos cancelados

Retorna a lista de pedidos cancelados pela Goomer nas últimas 4 horas em um objeto do tipo OrderList.

O cancelamento é realizado pelo painel de pedidos disponível para a loja ou automaticamente pela Goomer, em caso de de exceção. O retorno possui apenas os IDs dos pedidos para que sejam consultados pela rota de detalhes do pedido posteriormente, se for necessário.

Os pedidos retornados nessa rota devem ser cancelados na automação, caso já tenham sido integrados.

Pedidos que não foram aceitos ou recusados pela automação em até 90 segundos são cancelados automaticamente e notificados via webhook de cancelamento e via consulta de pedidos cancelados.

/orders/v1/list/cancelled

GET https://api-integration.goomer.app/orders/v1/list/cancelled

Headers

Name	Type	Description
x-api-key	string	Token de autenticação

200

{
    "orders: [
        53434316,
        9234324,
        89555444,
        702859
    ]
}

401 Token inválido ou expirado. Atualize o token e tente novamente.

Unauthorized

Detalhes de pedido

Busca os produtos e demais detalhes de um pedido à partir de seu id. Retorna um objeto Order.

Os detalhes dos pedidos ficam disponíveis para consulta durante um período de 8 horas.

/orders/v1/details/:orderId

GET https://api-integration.goomer.com.br/orders/v1/details/:orderId

Path Parameters

Name	Type	Description
orderId	string	id do pedido

Headers

Name	Type	Description
x-api-key	string	Token de autenticação

200 Retorna todas as informações de um pedido. O exemplo abaixo possui todos os campos possíveis. Consultar nos modelos os retornos em cada caso, que variam de acordo com o modo de operação.

{
    "id": 8402831109,
    "externalId": "894fa0fd-ad18-4d85-802b-e7abb358d282",
    "status": "pending",
    "deviceType": "smartphone",
    "table":"10",
    "tab": "203",
    "identifierName": "Maria",
    "identifierCode": "102",
    "operation": "delivery",
    "subtotal": 42.0,
    "discount": 4.2,
    "total": 37.8,
    "deliveryWay": "delivery",
    "deliveryFee": 3,
    "serviceFee": 0,
    "scheduled": false,
    "scheduledTo": "2020-02-20 15:00+0300",
    "address": {
        "zipCode": "11222333",
        "street": "Rua Acácias",
        "streetNumber": "392",
        "complement": "ap 409",
        "neighborhood": "Jardim Primavera",
        "reference": "Ed. Tulipa",
        "city": "Sorocaba",
        "state": "SP"
    },
    "customer": {
        "phone": "[phone]",
        "cpf": "11122233344",
        "name": "Maria da Silva"
    },
    "cpfFiscal": "11122233344",
    "payments": [
        {
            "type": "credit",
            "method": "online",
            "provider": "mpago",
            "flag": "VISA",
            "nsu": "12221091",
            "value": 37.8
        }
    ],
    "paymentChange": 0,
    "products": [
        {
            "name": "Açaí grande",
            "price": 15,
            "code": "10",
            "quantity": 2,
            "extras": [
                {
                    "name": "Banana",
                    "price": 1,
                    "code": "11",
                    "quantity": 2
                },
                {
                    "name": "Granola",
                    "price": 3,
                    "code": "12",
                    "quantity": 1
                }
            ],
            "observations": [
                "Sem cebola",
                "Sem molho"
            ]
        },
        {
            "name": "Água sem gás",
            "price": 4,
            "code": "20",
            "quantity": 1,
            "extras": [],
            "observations": [
                "Sem gelo"
            ]
        }
    ]
}

401 Token inválido ou expirado. Atualize o token e tente novamente.

Unauthorized

404 Pedido não encontrado.

Not Found

Aceitar pedido

Para o PDV indicar que aceitou a integração do pedido ele deve chamar esta rota. Após isso, o pedido com o id informado não retornará mais na lista de novos pedidos.

O aceite do pedido deve ser realizado assim que o PDV processar o pedido. Pedidos que não forem aceitos em até 90 segundos serão cancelados automaticamente.

/orders/v1/accept/:orderId

POST https://api-integration.goomer.app/orders/v1/accept/:orderId

content-type: application/json

Path Parameters

Name	Type	Description
orderId	string	id do pedido

Headers

Name	Type	Description
x-api-key	string	Token de autenticação

Request Body

Name	Type	Description
externalId	string	A software house pode fornecer um id externo para pedido, caso desejar

200 Pedido aceito com sucesso.

OK

400 O campo externalId é opcional e possui um limite de 255 caracteres.

externalId too long

401 Token inválido ou expirado. Atualize o token e tente novamente.

Unauthorized

404 Caso o pedido com o id informado não seja encontrado, um erro 404 é retornado.

Not Found

409 O pedido foi cancelado e não pode ser aceito.

Conflict

Recusar pedido

Em caso de erro de integração, a automação pode recusar o pedido, para que o restaurante faça o processo de forma manual. O pedido deve ser recusado por meio desta rota caso não seja possível integrá-lo, seja por um código inválido ou qualquer outro tipo de erro que impeça a integração.

O PDV pode enviar uma mensagem indicando qual foi o erro ocorrido. Essa mensagem será exibida para o restaurante no painel de pedidos Goomer, conforme a imagem abaixo:

Detalhe do pedido com erro de integração

Esta rota é exclusiva para recusar pedidos devido à erro de integração. Não utilize-a para apontar cancelamentos realizados pela operação do restaurante.

/orders/v1/deny/:orderId

POST https://api-integration.goomer.app/orders/v1/deny/:orderId

content-type: application/json

Path Parameters

Name	Type	Description
orderId	string	id do pedido

Headers

Name	Type	Description
x-api-key	string	Token de autenticação

Request Body

Name	Type	Description
message	string	Mensagem de erro que será exibida para o resturante. É recomendado que seja uma frase simples e em português.

200 Pedido recusado com sucesso.

OK

401 Token inválido ou expirado. Atualize o token e tente novamente.

Unauthorized

404 Pedido não encontrado.

Not Found

409 O pedido já foi aceito e não pode ser recusado. Para cancelá-lo utilize a rota para cancelar pedido.

Conflict

Atualizar status de pedido

Pode ser utilizado pela automação para atualizar o status do pedido para que o cliente possa receber atualizações.

Os status possíveis para esta rota são: preparing, delivering e finished. Eles são descritos na tabela de status de pedido.

Para atualizar o pedido para os status accepted e canceled utilize as rotas de aceite e cancelamento de pedido.

Só é possível atualizar um pedido dentro de um período de 8 horas.

/orders/v1/update/:orderId

POST https://api-integration.goomer.app/orders/v1/update/:orderId

content-type: application/json

Path Parameters

Name	Type	Description
orderId	string	id do pedido

Headers

Name	Type	Description
x-api-key	string	Token de autenticação

Request Body

Name	Type	Description
status	string	Novo status do pedido. Os valores possíveis valores estão descritos na tabela de status

200 Status do pedido atualizado com sucesso.

OK

400 Payload inválido. Verifique o formato dos dados e se o status enviado é um dos tipos permitidos: preparing, delivering, finished

Invalid parameters!

401 Token inválido ou expirado. Atualize o token e tente novamente.

Unauthorized

404 Pedido não encontrado.

Not Found

409 Status do pedido não pode ser atualizado pois ainda não aceito ou foi cancelado.

Conflict

Cancelar pedido

Caso o pedido seja cancelado pelo restaurante através do PDV, deve ser realizado o cancelamento do pedido por meio desta rota. Quando o cancelamento é efetuado através desta rota, o webhook de cancelamento não é disparado e o pedido não será listado na consulta de pedidos cancelados.

Só é possível cancelar pedidos que já foram aceitos pela rota de aceite de pedido.

Só é possível cancelar pedidos dentro de um período de 8 horas.

/orders/v1/cancel/:orderId

POST https://api-integration.goomer.app/orders/v1/cancel/:orderId

Path Parameters

Name	Type	Description
orderId	string	id do pedido

Headers

Name	Type	Description
x-api-key	string	Token de autenticação

200 Pedido cancelado com sucesso.

OK

401 Token inválido ou expirado. Atualize o token e tente novamente.

Unauthorized

404 Pedido não encontrado.

Not Found

409 Pedido ainda não foi aceito pelo PDV e por isso não pode ser cancelado.

Conflict

Modelos

Os campos marcados com * são obrigatórios e estarão sempre presentes nos retornos

OrderList

Campo	Tipo	Descrição
orders*	array<int>	Lista de ids de pedidos

Order

Campo	Tipo	Descrição
id*	int	id do pedido
orderNumber*	int	Número sequencial do pedido que é exibido no painel de pedidos da Goomer. Este número não é único e a contagem é zerada todos os dias.
externalId	string	id externo do pedido. Definido pela automação no momento do aceite do pedido
status*	string	Status do pedido: pending, accepted, preparing, delivering, finished, canceled (veja a tabela de status de pedido)
deviceType*	string	Plataforma que originou o pedido: smartphone, tablet, kiosk (veja a tabela de tipos de dispositivo)
table	string	Número da mesa (apenas para os produtos Goomer na loja e cardápio digital)
tab	string	Número da comanda (apenas para os produtos Goomer na loja e cardápio digital)
identifierName	string	Nome do cliente para identificação do pedido. Este é o nome que deverá ser chamado para que o cliente retire seu pedido (apenas para os modos de operação terminal e kiosk)
identifierCode	string	Número de identificação do pedido. Este é o número que deve ser anunciado para que o cliente retire seu pedido. Também pode ser o número de um pager (apenas para os modos de operação terminal e kiosk , veja tabela de tipos de operação)
operation*	string	Tipo de operação: delivery, takeaway, table, tab, terminal, kiosk (veja tabela de tipos de operação)
subtotal*	float	Valor total dos produtos, sem descontos nem taxas de entrega/serviço
discount*	float	Valor de desconto
total*	float	Valor total do pedido com eventuais descontos e taxas de entrega e serviço inclusas
deliveryWay*	string	Forma de entrega: delivery, onsite, takeaway (veja a tabela de formas de entrega)
deliveryFee*	float	Taxa de entrega
serviceFee*	float	Taxa de serviço
orderDateTime*	string	Data e hora que o pedido foi realizado no formato ISO 8601 em UTCAAAA-MM-DDTHH:mm:ssZ. Exemplo: 2021-02-20T16:00:00Z
deliveryDateTime	string	Data e hora limite para entrega do pedido no formato ISO 8601 em UTCAAAA-MM-DDTHH:mm:ssZ. Por exemplo: para um tempo de espera de 30 à 60 minutos de um pedido realizado na cidade de São Paulo às 15h do dia 20/02/2021, o valor deste campo será 2021-02-20T19:00:00Z
scheduled*	boolean	Indica se o pedido foi agendado para uma data e hora específica
scheduledDateTime* (Obrigatório para pedidos agendados)	string	Data e hora inicial para entrega do pedido no formato ISO 8601 em UTC AAAA-MM-DDTHH:mm:ssZ. A janela do agendamento é de 30 minutos. Por exemplo: caso o cliente escolha a entrega entre 14h30 e 15h, do dia 20/02/2021, na cidade de São Paulo, o valor deste campo será 2021-02-20T17:30:00Z
address	Address	Objeto com informações do endereço de entrega
customer	Customer	Objeto com informações do cliente
cpfFiscal	string	CPF para ser utilizado na emissão de cupom fiscal, sem formatação
payments	array<Payment>	Lista de pagamentos
paymentChange	float	Valor pago para cálculo do troco para pagamento em dinheiro
products*	array<Product>	Lista de produtos

Product

Campo	Tipo	Descrição
name*	string	Nome do produto
type*	string	Tipo do produto: default, combo, pizza (veja a tabela de tipos de produto)
price*	float	Preço unitário
code*	string	Código do produto
quantity*	float	Quantidade do produto
observations	array<string>	Lista de observações de preparo. Exemplo: ["Sem cebola", "Sem tomate"]
extras	array<Extra>	Lista de extras

Extra

Campo	Tipo	Descrição
name*	string	Nome do produto extra
price*	float	Preço unitário do produto extra
code*	string	Código do produto extra
quantity*	float	Quantidade do produto extra para cada unidade do produto ao qual pertence

Payment

Campo	Tipo	Descrição
type*	string	Tipo de pagamento:cash ,credit, debit , voucher, unknown (veja a tabela de tipos de pagamento)
method*	string	Meio de pagamento: pinpad, online, offline, link, qrcode (veja a tabela de meios de pagamento)
provider	string	Provedor do pagamento: mpago, pagseguro (veja a tabela de provedores de pagamento)
flag	string	Bandeira do cartão utilizado
nsu	string	NSU do pagamento retornado pelo provedor
value*	float	Valor pago

Customer

Campo	Tipo	Descrição
phone	string	Número de telefone informado pelo cliente no formato [phone]
name	string	Nome do cliente
cpf	string	CPF do cliente, sem formatação

Address

Campo	string	Descrição
zipCode	string	CEP do cliente, sem formatação
street*	string	Nome da rua
streetNumber*	int	Número da rua
complement	string	Complemento do endereço
neighborhood*	string	Bairro do endereço
reference	string	Referência de do endereço
city*	string	Cidade
state*	string	Sigla do estado em dois caracteres

Tabelas

Tipos de produto

Tipo	Descrição
default	Produto normal
combo	Em breve
pizza	Em breve

Formas de entrega

Tipo	Descrição
delivery	Pedido para entrega
takeaway	Pedido para retirada/viagem
onsite	Pedido para consumo no local

Tipos de operação

Tipo	Descrição
delivery	Operação de delivery com GoomerGo
takeaway	Operação para retirada com GoomerGo
table	Modo mesa para operar com tablets ou Goomer na Loja
tab	Modo comanda para operar com tablets ou Goomer na Loja
terminal	Modo terminal de lançamento para operar com tablets. Nesse modo não há pagamento. O cliente faz o lançamento dos produtos em sua comanda por meio um QR Code e faz o pagamento apenas antes de ir embora, com um atendente
kiosk	Modo totem para operar com o Goomer Fast. O pagamento é realizado no próprio dispositivo ou em dinheiro, com um atendente
checkout	Em breve

Status de pedido

Status	Descrição
pending	Pedido pendente. É o primeiro status do pedido
accepted	Pedido aceito. Quando o pedido é aceito pela integração ele é movido para este status automaticamente
preparing	Pedido começou a ser preparado
delivering	Pedido saiu para entrega
finished	Pedido foi entregue e concluído com sucesso
canceled	Pedido foi cancelado

Tipos de dispositivo

Tipo	Descrição
smartphone	GoomerGo e Goomer na loja
tablet	Cardápio digital em tablet na mesa
kiosk	Goomer Fast

Tipos de pagamento

Tipo	Descrição
cash	Pagamento em dinheiro
credit	Pagamento no cartão crédito
debit	Pagamento no cartão débito ou PIX
voucher	Pagamento com vales-refeição
unknown	Forma de pagamento desconhecida. Geralmente para casos de pagamento por meio de link de pagamento ou QRCode

Meios de pagamento

Tipo	Descrição
pinpad	Pagamento realizado por meio de pinpad integrado à aplicação
online	Pagamento realizado por meio de checkout transparente dentro da aplicação
offline	Pagamento realizado para um antedente, seja dinheiro, cartão ou PIX, fora da aplicação, que exige uma confirmação do recebimento por um antedente
link	Pagamento realizado por meio de link de pagamento
qrcode	Pagamento realizado por meio de QR Code

Provedores de pagamento

Tipo	Descrição
mpago	Mercado Pago
pagseguro	PagSeguro