Contas v1

Primeira versão da API de contas

As contas são manipuladas a partir da rota abaixo.

Criação/Atualização de uma conta

Sempre que a conta de um cliente for atualizada no PDV, a rota abaixo deve ser chamada. Pode ser qualquer atualização na conta:

• Adição de produtos.

• Cancelamento de produto.

• Mudança de status da conta.

• Fechamento da conta.

Essa rota funciona como criação ou atualização de uma conta. A atualização não é incremental e sim completa, ou seja, a cada chamada devem ser enviados todos os itens presentes na conta.

/bills/v1/update

PUT -/bills/v1/update

content-type: application/json

Headers

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

Request Body

Name	Type	Description
<Bill>	object	O modelo Bill especificado logo abaixo.

200 Conta recebida com sucesso

OK

422 Ao menos um dos campos "table" ou "tab" deve ser informado no body da requisição

At least one of these fields are required [ table | tab ]

Exemplo de requisição:

curl --location --request PUT 'https://api-integration.goomer.app/bills/v1/update' \
--header 'x-api-key: {token}' \
--header 'Content-Type: application/json' \
--data-raw '{
      "status": "AVAILABLE",
      "externalId": "123",
      "products": [{
        "code": "1234",
        "name": "product name",
        "price": 10.5,
        "quantity": 2,
        "type": "default",
        "date": "",
        "observations": [ "obs" ],
        "extras": [{
          "name": "teste de la api",
          "price": 3.2,
          "quantity": 2
        }]
      }],
      "total": 34.8,
      "subtotal": 33.8,
      "service": 2.0,
      "discount": 1.0,
      "table": "10"
    }'

Obtenção de solicitações de fechamento de conta

O PDV deve realizar uma requisição para a rota abaixo em um pooling a fim de obter as solicitações de fechamento de conta realizadas pelos clientes através do tablet

bills/v1/close-request

GET -/bills/v1/close-request

content-type: application/json

Headers

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

200: OK Lista com as solicitações de fechamento de conta

[
  {
    "operation": "tab",
    "table": "26",
    "tab": "1"
  },
  {
    "operation": "table",
    "table": "27"
  }
]

Exemplo de requisição

curl --request GET \
  --url https://api-integration.goomer.app/bills/v1/close-request \
  --header 'x-api-key: {token}'

Confirmação de solicitação de fechamento de mesa

O PDV deve realizar uma requisição para a rota abaixo para cada uma das solicitações de fechamento de conta obtidas através da requisição apresentada no tópico anterior.

bills/v1/close-request

POST -/bills/v1/close-request

content-type: application/json

Headers

Name	Type	Description
x-api-key*	String	Token de Autenticação

Request Body

Name	Type	Description
<Bill Identifier>	String	O modelo Bill Identifier

200: OK Conta fechada com sucesso

{
    // Response
}

Exemplo de requisição

curl --request POST \
  --url https://api-integration.goomer.app/bills/v1/close-request \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: {token}' \
  --data '{
    "operation": "tab",
    "table": "27",
    "tab": "1"
}'

Fechamento de conta

O PDV deve realizar uma requisição para a rota abaixo para fechamento de uma conta, seja ela Comanda ou Mesa.

bills/v1/close

POST -/bills/v1/close

content-type: application/json

Headers

Name	Type	Description
x-api-key*	String	Token de Autenticação

Request Body

Name	Type	Description
<Bill Identifier>*	String	O modelo Bill Identifier

200: OK Conta fechada com sucesso

{}

Exemplo de requisição

curl --request POST \
  --url https://api-integration.goomer.app/bills/v1/close \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: {token}' \
  --data '{
    "operation": "tab",
    "table": "27",
    "tab": "1"
}'

Modelos

Os campos campos marcados com * são obrigatórios

Bill

Campo	Tipo	Descrição
status	string	Um dos Status especificados logo abaixo.
tab	string	O número de origem da conta.
table	string	O número de origem da mesa.
externalId	string	O ID no PDV.
total*	number	O valor total da conta em reais, considerando descontos e taxas.
subtotal*	number	O valor total da conta em reais sem taxa de serviço ou desconto. É​ soma de todos os valores dos produtos e seus extras, multiplicados por suas respectivas quantidades.
service*	number	O valor da taxa de serviço em reais.
discount*	number	O valor do desconto em reais. É​ um valor positivo.
products*	array<Product>	Lista com todos os produtos presentes na conta. Tipo Product especificado logo abaixo.

Os campos table e tab se referem ao modo de operação. Se o modo for mesa, enviar o número da mesa no campo table. Se o modo for comanda, enviar o numero da comanda no campo tab. Importante ressaltar que se houver o parâmetro tab, então o table será desconsiderado. Todavia é necessário pelo menos um dos campos (table ou tab) para o correto funcionamento da rota.

Status

Valor	Descrição
AVAILABLE	Disponível: Não está em uso. Aceita lançar pedidos
CONSUMING	Consumindo: Em uso. Aceita lançar pedidos
IN_PAYMENT	Em pagamento: Não aceita lançar pedidos
CLOSED	Fechada: Um novo pedido abre uma nova conta. Os campos obrigatórios de total, subtotal, service e discount, podem ser preenchidos com 0,00. Já o campo products pode ser enviado como um array vazio
CANCELED	Cancelada: Pedido cancelado. Os campos obrigatórios podem ser enviados da mesma maneira que no CLOSED

Product

Campo	TIpo	Descrição
code*	string	O código do produto no PDV.
name*	string	O nome do produto.
price*	float	O preço do produto em reais.
quantity*	float	A quantidade do produto. Deve ser maior que 0.
type*	string	Enviar com o valor "default".
date*	string	A data no formato ISO 8601 em UTCAAAA-MM-DDTHH:mm:ssZ. Note que deve ser enviado sem milisegundos. Caso não haja data, enviar em branco.
extras*	array<Extra>	A lista de opcionais por produto. Se não houver mandar array vazio.
observations*	array<string>	Lista de observações sobre o produto.

Extra

Campo	Tipo	Descrição
name*	string	O nome do opcional.
price*	float	O preço do opcional.
quantity*	float	A quantidade do opcional. Deve ser um valor maior que 0.
code *	string	O código do extra no PDV.

Bill Identifier

Campo	Tipo	Descrição
operation*	string	O nome da operação: table ou tab
table*	string	Número da Mesa
tab	string	Número da Comanda