Convenções e erros

Esta página reúne as regras que valem para todos os endpoints. Leia uma vez antes de começar a implementar: quase todo erro de integração nasce de algo aqui.

Como ler as páginas de referência

Cada operação aparece com o método e o caminho relativo à URL base:

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

Tudo entre chaves é substituído pelo valor real — as chaves não fazem parte da URL:

Errado	Certo
`/places/{idPlace}/tabs/{idTab}/checkin`	`/places/P-PDV/tabs/006/checkin`

O endereço final junta a URL base com o caminho:

https://api-demo.letsenjoy.it/pos/places/P-PDV/tabs/006/checkin

URL base

Homologação: https://api-demo.letsenjoy.it/pos
Produção:    https://api.letsenjoy.it/pos

Todos os caminhos das páginas seguintes são relativos a essa URL. Cada ambiente tem a sua própria chave — veja Autenticação.

Headers

x-api-key: SUA_CHAVE_DE_API
Content-Type: application/json

Content-Type é necessário sempre que a chamada tiver corpo, ou seja, em POST e PUT.

Identificadores

Campo	O que é	De onde vem	Exemplo
`idPlace`	Código do estabelecimento	Fornecido pela Enjoy.it	`P-PDV`
`idTab`	Número impresso na comanda	Lido ou digitado no caixa	`006`
`rfid`	Código do chip do cartão	Lido pelo leitor RFID/NFC	`4623227593`
`reference`	Código do cliente no seu sistema	Você define	`cliente-123`
`uid`	Código interno do cliente na Enjoy.it	Vem nas respostas	`5FS6DS0B...`
`idTransaction`	Código único de uma transação	Vem nas respostas	`e2f64f70-...`
`idTap`	Código de uma torneira	Fornecido pela Enjoy.it	`T-01`

Envie números de comanda com três dígitos. A API completa com zeros à esquerda quando você manda menos, mas usar o formato cheio evita confusão em log e conciliação: mande 006, não 6.

Datas e valores

Este é o ponto onde sistemas brasileiros mais tropeçam, porque o formato da API não é o formato de tela:

Campo	Errado	Certo
Valor	`"R$ 12,80"`	`12.8`
Valor	`"12,80"`	`12.8`
Valor	`1280` (centavos)	`12.8`
Data	`"20/10/2026 14:35"`	`"2026-10-20T17:35:18.417Z"`

As regras:

Valores são números decimais em reais, com ponto como separador. Não são centavos, não são texto e não levam símbolo de moeda.
Datas seguem o padrão ISO 8601 em UTC — o Z no fim indica isso. Horário de Brasília é UTC−3: 14:35 em São Paulo é 17:35Z.
Em filtros por período, startAt e finishAt andam sempre juntos.

Modelo de consumidor

{
  "name": "Maria Silva",
  "cellphone": "+5511999999999",
  "consumerReference": "cliente-123",
  "document": "12345678900",
  "email": "maria@example.com",
  "showLeaderboard": true,
  "gender": "female",
  "birthdate": "1990-05-20",
  "region": {
    "street": "Alameda Exemplo",
    "postalcode": "04547000",
    "number": "100",
    "neighborhood": "Vila Olímpia",
    "city": "São Paulo",
    "state": "São Paulo"
  }
}

Campo	Obrigatório	Observação
`name`	Sim	Nome apresentado na operação e no totem
`consumerReference`	Recomendado	O código do cliente no seu sistema. Sem ele, a conciliação depende só da comanda
`cellphone`	Não	Preferencialmente no formato internacional, com `+55`
`document`	Não	Documento do consumidor, só dígitos
`email`	Não	E-mail do consumidor
`showLeaderboard`	Não	Permissão para aparecer em ranking
`gender`	Não	`male`, `female` ou `other`
`birthdate`	Não	Data de nascimento
`region`	Não	Endereço do consumidor

Modelo de check-in

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

Campo	Obrigatório	Observação
`plan`	Sim	`prepaid` ou `postpaid`
`consumer`	Sim	Dados do consumidor
`hasConsumptionLimit`	Não	Em pré-pago use `true`, senão a torneira libera sem saldo
`balance`	Condicional	Saldo disponível quando existe limite
`consumptionIpn`	Não	Webhook chamado após cada consumo. Só informe se você usa webhook
`balanceIpn`	Não	Endereço seu que a Enjoy.it consulta para saber o saldo atualizado
`broughtGlass`	Não	Indica se o cliente trouxe o próprio copo
`glassPrice`	Não	Valor do copo, quando a operação cobra por ele

Modelo de produto externo

Use este modelo para mandar itens vendidos no seu PDV para o extrato da Enjoy.it, seja por POST .../transactions ou na lista products do checkout.

{
  "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
}

O createdAt participa da identificação da transação: reenviar a mesma operação com a mesma data não deve criar um segundo lançamento. Use transactionReference para apontar para o registro correspondente no seu sistema.

Modelo de transação

É o que você recebe ao consultar o extrato ou por webhook:

{
  "idTransaction": "e2f64f70-e320-4c4b-acae-d4aff934b8a0",
  "createdAt": "2026-10-20T17:35:18.417Z",
  "idPlace": "P-PDV",
  "idTab": "006",
  "rfid": "4623227593",
  "consumerReference": "cliente-123",
  "product": "Chopp Pilsen",
  "sku": "PILSEN",
  "mlServed": 340.3,
  "sellingPrice": 0.05,
  "total": 17.02,
  "type": "D",
  "reversed": false
}

Campo	O que fazer com ele
`total`	É o valor a lançar. Já vem calculado; não recalcule por preço de tabela
`sku`	O código do produto. Ver abaixo — é o campo que liga a transação ao seu catálogo
`mlServed`	O volume servido. Vale exibir: explica por que o valor não é redondo
`sellingPrice`	O preço por mililitro. Não é o preço do copo
`idTransaction`	Grave para não lançar duas vezes
`reversed`	Se `true`, a transação foi estornada e não deve ser cobrada

O campo `sku`

O produto de cada torneira e o preço por mililitro são cadastrados no sistema da Enjoy.it — seu PDV não envia preço nem escolhe produto.

Para que você consiga lançar o consumo no item certo do seu catálogo, o sku é configurado no cadastro do produto dentro da Enjoy.it e pode receber o código do produto no sistema integrador. A transação chega então com um identificador que o seu PDV já conhece, em vez de exigir que você case por nome — que muda a cada troca de barril.

Combine o preenchimento dos sku durante a homologação.

`type`	Significado
`D`	Débito: consumo realizado na Enjoy.it
`C`	Crédito: recarga
`P`	Produto registrado pelo PDV parceiro

Respostas de sucesso

Status	Quando acontece
`200 OK`	Consulta, atualização, checkout, reset ou exclusão concluída
`201 Created`	Check-in, recarga ou transação criada

Operações que não precisam devolver dados respondem com um objeto vazio. Isso é sucesso, não falta de resposta:

{}

Erros

Status	Significado	O que fazer
`400 Bad Request`	Conteúdo inválido, campo faltando ou regra de negócio não atendida	Corrija o envio. Repetir igual não resolve
`403 Forbidden`	Sua chave não tem acesso a esse estabelecimento	Confira a chave e o `idPlace`
`404 Not Found`	Comanda, cartão, cliente ou recurso não existe	Confira o identificador. Em comanda, confira o cadastro da loja
`409 Conflict`	Recurso ou operação duplicada	Verifique se você já não enviou. Não force
`429 Too Many Requests`	Chamadas demais em pouco tempo	Espere e tente de novo, espaçando as chamadas
`500 Internal Server Error`	Falha do nosso lado	Pode tentar de novo. Se persistir, acione o suporte

Erros de negócio conhecidos:

Código	Mensagem	Causa comum
`4001`	Credencial já possui consumo aberto	Check-in em uma comanda que nunca recebeu checkout
`4002`	Comanda ou credencial não está aberta	Lançamento após o checkout, ou check-in que falhou
`4003`	Saldo insuficiente	Pré-pago sem crédito, ou saldo não sincronizado
`4004`	Já existe transação com a data informada	Reenvio da mesma transação. Geralmente é a proteção funcionando
`4041`	Número de comanda não encontrado	Comanda inexistente no cadastro da loja

Como não cobrar o cliente duas vezes

Toda transação tem um identificador único. Antes de lançar, verifique se já gravou aquele identificador; se já gravou, ignore e responda sucesso.

É o que evita este cenário:

Cliente tira um chope de R$ 12,80
A Enjoy.it entrega o consumo ao seu sistema
Seu sistema lança na comanda......... OK
A resposta se perde (queda de rede, timeout)
A Enjoy.it considera que falhou e entrega de novo
Seu sistema lança de novo........... o cliente paga R$ 25,60

Identificador	Onde aparece
`idTransaction`	Campo pronto, único por transação — o mais simples de usar
`uid` + `createdAt`	A identificação estável: consumidor + data e hora exata da servida

Grave o identificador antes do lançamento financeiro. Assim uma tentativa repetida encontra o registro, responde sucesso e não duplica nada.

O mesmo cuidado vale na consulta: consultar o extrato duas vezes traz as mesmas transações nas duas respostas. Grave apenas as que ainda não estão no seu banco.

Como ler as páginas de referência​

URL base​

Headers​

Identificadores​

Datas e valores​

Modelo de consumidor​

Modelo de check-in​

Modelo de produto externo​

Modelo de transação​

O campo sku​

Respostas de sucesso​

Erros​

Como não cobrar o cliente duas vezes​