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

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