Comandas

Use estes endpoints quando o operador conhece o número impresso da comanda, mas não precisa ler seu chip RFID. A Enjoy.it mantém o vínculo entre idTab e RFID.

Resumo

Método	Endpoint	Finalidade
GET	/places/{idPlace}/tabs/{idTab}	Consultar uma comanda
GET	/places/{idPlace}/tabs	Listar comandas abertas
POST	/places/{idPlace}/tabs/{idTab}/checkin	Abrir uma comanda
PUT	/places/{idPlace}/tabs/{idTab}/customers	Alterar consumidor
GET	/places/{idPlace}/tabs/{idTab}/transactions	Consultar transações
POST	/places/{idPlace}/tabs/{idTab}/transactions	Registrar produto externo
DELETE	/places/{idPlace}/tabs/{idTab}/transactions/{idTransaction}	Estornar transação
POST	/places/{idPlace}/tabs/{idTab}/recharges	Registrar recarga
PUT	/places/{idPlace}/tabs/{idTab}/balance	Atualizar saldo
PUT	/places/{idPlace}/tabs	Trocar a comanda
POST	/places/{idPlace}/tabs/{idTab}/checkout	Encerrar a comanda
POST	/places/{idPlace}/tabs/{idTab}/reset	Reiniciar a comanda

Parâmetros e erros comuns

Valem para todos os endpoints desta página, e por isso não se repetem em cada um.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
idPlace	string	Sim	Código do estabelecimento. Precisa estar no escopo da sua chave
idTab	string	Sim	Número impresso na comanda. A API completa com zeros à esquerda: 6 vira 006

Erros comuns

Status	Código	Mensagem	Quando acontece
400	—	validação do payload	Campo obrigatório ausente ou com tipo errado
403	—	Not authorized to interact with this place (idPlace)	A chave não tem acesso a esse estabelecimento
404	4041	idTab not found!	O número da comanda não existe no cadastro da loja
404	4042	RFID card not found in userRfid table.	A comanda existe, mas não há credencial ativa vinculada a ela
423	4231	Place suspended!	O estabelecimento está suspenso

Consultar uma comanda

Retorna o estado atual da comanda e o consumidor vinculado a ela.

GET /places/{idPlace}/tabs/{idTab}

Resposta 200

Campo	Tipo	Descrição
idTab	string	Número da comanda
rfid	string	Código do chip resolvido a partir do número
uid	string	Identificador do consumidor na Enjoy.it
plan	string	prepaid ou postpaid
status	string	Estado da credencial. enable indica que ela libera consumo
accountBalance	number	Saldo disponível, em reais
hasConsumptionLimit	boolean	Se true, a torneira respeita o saldo. Vem false quando não definido
createdAt	string	Data de abertura da sessão, em ISO 8601
consumerReference	string	Código do consumidor no seu sistema
consumptionIpn	string	Webhook de consumo configurado nesta sessão
balanceIpn	string	Endereço consultado para obter o saldo
openTapIpn	string	Webhook de mudança de estado da torneira
broughtGlass	boolean	Se o consumidor trouxe o próprio copo
glassPrice	number	Valor do copo, quando a operação cobra por ele
qrCode	string	QR Code vinculado, quando houver
customer	objeto	Dados do consumidor. Ausente se não houver consumidor vinculado

Campos de customer:

Campo	Tipo	Descrição
uid	string	Identificador do consumidor na Enjoy.it
name	string	Nome
document	string	Documento
cellphone	string	Telefone
consumerReference	string	Código do consumidor no seu sistema
email	string	E-mail
gender	string	male, female ou other
birthdate	string	Data de nascimento em ISO 8601
region	objeto	Endereço: street, postalcode, number, neighborhood, city, state

{
  "accountBalance": 120,
  "createdAt": "2026-08-02T19:43:29.416Z",
  "hasConsumptionLimit": true,
  "consumerReference": "cliente-123",
  "idTab": "006",
  "plan": "prepaid",
  "rfid": "4623227593",
  "status": "enable",
  "uid": "5FS6DS0BDERIWG9QL6ojfuLedg23",
  "customer": {
    "name": "Maria Silva",
    "cellphone": "+5511999999999",
    "consumerReference": "cliente-123"
  }
}

Só os erros comuns.

Listar comandas abertas

Retorna todas as comandas com sessão aberta no estabelecimento.

GET /places/{idPlace}/tabs

Query string

Parâmetro	Tipo	Obrigatório	Descrição
sources	string	Não	Filtra por origem. Aceita vários valores separados por vírgula
lastTransactionAfter	string	Não	Data em ISO 8601. Retorna apenas comandas com consumo posterior a ela

Resposta 200

Lista de objetos no mesmo formato de Consultar uma comanda.

[
  {
    "idTab": "006",
    "rfid": "4623227593",
    "plan": "prepaid",
    "accountBalance": 120,
    "status": "enable"
  }
]

Erros

Status	Mensagem	Quando acontece
400	Invalid lastTransactionAfter	A data enviada não é reconhecida como data válida

Abrir uma comanda

Vincula o consumidor à comanda e libera o consumo. É o check-in.

POST /places/{idPlace}/tabs/{idTab}/checkin

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
plan	string	Sim	prepaid ou postpaid
consumer	objeto	Sim	Dados do consumidor. Ver tabela abaixo
hasConsumptionLimit	boolean	Não	Em pré-pago use true, senão a torneira libera sem saldo
balance	number	Não	Saldo inicial em reais
bonus	number	Não	Crédito de cortesia em reais
consumptionIpn	string	Não	URL chamada a cada consumo. Informe apenas se você usa webhook
balanceIpn	string	Não	URL consultada pela Enjoy.it para obter o saldo antes de liberar a torneira
broughtGlass	boolean	Não	Indica que o consumidor trouxe o próprio copo
glassPrice	number	Não	Valor do copo, quando a operação cobra por ele
reopenTab	string	Não	Reabre uma sessão anterior em vez de criar uma nova
rfid	string	Não	Fixa o chip a ser usado, em vez de resolver pelo número da comanda

Campos de consumer:

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome apresentado no totem e nos relatórios
consumerReference	string	Não	Recomendado. O código do consumidor no seu sistema
cellphone	string	Não	Telefone, preferencialmente com +55
document	string	Não	Documento, apenas dígitos
email	string	Não	E-mail
gender	string	Não	male, female ou other
birthdate	string	Não	Data de nascimento
showLeaderboard	boolean	Não	Autoriza exibir o consumidor em ranking
optIns	objeto	Não	Permissões de contato. Contém marketing (boolean)
region	objeto	Não	Endereço: street, postalcode, number, neighborhood, city, state

{
  "plan": "postpaid",
  "hasConsumptionLimit": false,
  "consumer": {
    "name": "Maria Silva",
    "cellphone": "+5511999999999",
    "consumerReference": "cliente-123"
  },
  "consumptionIpn": "https://parceiro.example.com/enjoy/consumptions"
}

Resposta 201

Corpo vazio. Só entregue a comanda ao consumidor depois de receber este 201.

{}

Erros

Status	Código	Mensagem	Quando acontece
400	4001	This RFID card has an opened consumption.	A comanda já tem sessão aberta. Faça o checkout antes
422	4221	It was not possible to link the phone number with the document provided.	Telefone e documento pertencem a cadastros diferentes

Alterar consumidor

Troca ou completa os dados do consumidor de uma sessão já aberta, sem encerrá-la.

PUT /places/{idPlace}/tabs/{idTab}/customers

Corpo da requisição

Os mesmos campos de consumer em Abrir uma comanda — name é obrigatório.

{
  "name": "Maria Silva",
  "consumerReference": "cliente-123",
  "email": "maria@example.com"
}

Resposta 200

Corpo vazio.

{}

Só os erros comuns.

Consultar transações

Retorna o extrato da comanda: consumos de chope, recargas e produtos lançados pelo parceiro.

GET /places/{idPlace}/tabs/{idTab}/transactions

Query string

Parâmetro	Tipo	Obrigatório	Descrição
startAt	string	Não	Início do período em ISO 8601
finishAt	string	Não	Fim do período em ISO 8601

startAt e finishAt só têm efeito quando enviados juntos. Informar só um deles é o mesmo que não filtrar.

GET /places/P-PDV/tabs/006/transactions?startAt=2026-08-01T00:00:00.000Z&finishAt=2026-08-02T23:59:59.999Z

Resposta 200

Lista de transações, ordenada por createdAt.

Campo	Tipo	Descrição
idTransaction	string	Identificador único. Use para não lançar duas vezes
createdAt	string	Data e hora da transação, em ISO 8601
total	number	Valor a lançar, em reais. Já vem calculado
product	string	Descrição do item
sku	string	Código do produto. Pode ser configurado na Enjoy.it com o código do seu catálogo
mlServed	number	Volume servido. Ausente em produtos e recargas
sellingPrice	number	Preço por mililitro no consumo de chope
quantity	number	Quantidade, em produtos lançados pelo parceiro
type	string	D consumo, C recarga, P produto do parceiro
reversed	boolean	Se true, a transação foi estornada e não deve ser cobrada
bonus	number	Parte do valor paga com crédito de cortesia
paymentMethod	string	Meio de pagamento, em recargas
billing	string	Informação de faturamento
acknowledged	boolean	Se você já deu baixa nesta transação
acknowledgedAt	string	Data da baixa, em ISO 8601
acknowledgeReference	string	Referência do lançamento no seu sistema, enviada na baixa
idTap	string	Torneira onde o consumo aconteceu
idTab	string	Número da comanda
rfid	string	Chip da credencial
idPlace	string	Estabelecimento
uid	string	Consumidor na Enjoy.it. Com createdAt, identifica a transação
consumerReference	string	Código do consumidor no seu sistema
transactionReference	string	Referência enviada por você ao registrar
plan	string	prepaid ou postpaid
document	string	Documento do consumidor
category	string	Categoria, em produtos do parceiro

[
  {
    "idTransaction": "980a69f4-d629-5571-8a9f-99aa0293e4d6",
    "createdAt": "2026-08-02T19:43:29.416Z",
    "product": "IPA da Casa",
    "sku": "IPA-001",
    "mlServed": 320,
    "sellingPrice": 0.04,
    "total": 12.8,
    "type": "D",
    "reversed": false,
    "acknowledged": false,
    "idTap": "T-01",
    "idTab": "006",
    "rfid": "4623227593",
    "idPlace": "P-PDV",
    "uid": "5FS6DS0BDERIWG9QL6ojfuLedg23"
  }
]

Só os erros comuns.

Registrar produto externo

Lança na Enjoy.it um item vendido no seu PDV. A transação sensibiliza o saldo do consumidor, o que em pré-pago dispensa o PUT .../balance daquela venda.

POST /places/{idPlace}/tabs/{idTab}/transactions

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
createdAt	string	Sim	Data e hora da venda em ISO 8601. Participa da identificação da transação
product	string	Sim	Descrição do item
category	string	Sim	Categoria do item
quantity	number	Sim	Quantidade vendida
total	number	Não	Valor total da venda, em reais
sellingPrice	number	Não	Preço unitário praticado
price	number	Não	Preço de tabela
value	number	Não	Valor a debitar, quando diferente do total
sku	string	Não	Código do produto no seu catálogo
transactionReference	string	Não	Referência da venda no seu sistema
reference	string	Não	Referência auxiliar
reversed	boolean	Não	Marca a transação como estornada

{
  "createdAt": "2026-10-20T17:35:18.417Z",
  "product": "Coca-Cola lata",
  "category": "Bebidas",
  "transactionReference": "venda-987",
  "sku": "COCA350",
  "sellingPrice": 8.5,
  "quantity": 1,
  "total": 8.5
}

Resposta 201

A transação criada, no mesmo formato de Consultar transações, sempre com type: "P". Os campos mlServed e idTap não se aplicam e vêm ausentes.

Erros

Status	Código	Mensagem	Quando acontece
400	4002	This tab is not open.	A comanda não tem sessão aberta
400	4003	Insufficient funds!	Saldo insuficiente para o valor lançado
400	4004	There is already a transaction for this customer with the createdAt provided.	Reenvio da mesma venda. Normalmente é a proteção contra duplicidade funcionando

Estornar transação

Cancela um lançamento já registrado, devolvendo o valor ao saldo.

DELETE /places/{idPlace}/tabs/{idTab}/transactions/{idTransaction}

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
idTransaction	string	Sim	O idTransaction devolvido em Consultar transações

Não possui corpo.

Resposta 200

Corpo vazio.

{}

Erros

Status	Código	Mensagem	Quando acontece
404	4040	Transaction not found!	O idTransaction não pertence ao extrato dessa comanda

aviso

O estorno é uma operação financeira. Depois de receber sucesso, não repita a chamada; em caso de timeout, consulte o extrato e confira o campo reversed antes de tentar de novo.

Registrar recarga

Credita saldo na comanda. Chame somente depois de o pagamento ser aprovado pelo seu adquirente.

POST /places/{idPlace}/tabs/{idTab}/recharges

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
value	number	Sim	Valor creditado, em reais
paymentMethod	string	Não	debit-card, credit-card, cash ou on-the-house (cortesia)

{
  "value": 50,
  "paymentMethod": "credit-card"
}

Resposta 201

Corpo vazio. Só apresente o novo saldo ao consumidor depois deste 201.

{}

Erros

Status	Código	Mensagem	Quando acontece
404	—	Missing value!	value ausente ou não numérico. Repare que o status é 404, não 400
400	4002	This tab is not open.	A comanda não tem sessão aberta

Atualizar saldo

Sincroniza na Enjoy.it o saldo que o consumidor ainda tem disponível para chope.

PUT /places/{idPlace}/tabs/{idTab}/balance

Query string

Parâmetro	Tipo	Obrigatório	Descrição
relative	boolean	Não	Com true, o valor enviado é somado ao saldo atual em vez de substituí-lo

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
balance	number	Condicional	Novo saldo em reais, ou a variação quando relative=true
glassPrice	number	Condicional	Valor do copo

Pelo menos um dos dois precisa ser enviado.

{
  "balance": 200
}

Resposta 200

Corpo vazio.

{}

Erros

Status	Mensagem	Quando acontece
400	Missing balance or glassPrice.	Corpo vazio ou sem nenhum dos dois campos

Trocar a comanda

Transfere a sessão para outro cartão, preservando consumos e saldo. Use quando o consumidor perder ou danificar a comanda.

PUT /places/{idPlace}/tabs

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
currentIdTab	string	Sim	Número da comanda em uso. Completado com zeros à esquerda
newIdTab	string	Sim	Número da comanda que passará a valer. Precisa estar livre

{
  "currentIdTab": "006",
  "newIdTab": "021"
}

Resposta 200

Corpo vazio.

{}

Erros

Status	Mensagem	Quando acontece
400	Missing currentIdTab or newIdTab.	Faltou um dos dois campos
400	The current tab is not in use.	A comanda de origem não tem sessão aberta
400	The new tab is already in use.	A comanda de destino já está com outro consumidor

Encerrar a comanda

Encerra a sessão e bloqueia a comanda contra novas servidas. Chame quando o consumidor for embora.

POST /places/{idPlace}/tabs/{idTab}/checkout

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
products	lista de objetos	Sim	Itens do seu PDV ainda não enviados. Mande [] quando não houver nenhum

Cada item de products usa os mesmos campos de Registrar produto externo.

{
  "products": [
    {
      "createdAt": "2026-10-20T17:35:18.417Z",
      "product": "Coca-Cola lata",
      "category": "Bebidas",
      "transactionReference": "venda-987",
      "sellingPrice": 8.5,
      "quantity": 1,
      "total": 8.5
    }
  ]
}

aviso

Não repita aqui produtos já enviados por Registrar produto externo — seriam lançados duas vezes.

Resposta 200

Corpo vazio. Só libere o consumidor e reutilize o cartão depois deste 200.

{}

Erros

Status	Código	Mensagem	Quando acontece
400	4002	This tab is not open.	A comanda já foi encerrada ou nunca foi aberta

Reiniciar a comanda

Desassocia o ciclo atual da credencial, deixando o cartão pronto para outro uso.

POST /places/{idPlace}/tabs/{idTab}/reset

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
keepBalance	boolean	Não	Com true, o saldo permanece disponível para o próximo ciclo

O corpo em si é obrigatório: envie ao menos {}.

{
  "keepBalance": false
}

Resposta 200

Corpo vazio.

{}

Só os erros comuns.