Receber os consumos e dar baixa
Esta página vale para os dois modelos financeiros. O que muda entre pré-pago e pós-pago é o controle de saldo; a forma de trazer os chopes para o seu sistema é a mesma.
Escolha uma das duas opções abaixo. Se ainda não decidiu, veja a pergunta que define isso.
Opção A — Webhook (a Enjoy.it avisa você)
Requer que o seu sistema tenha um endereço público HTTPS. Informe esse endereço em consumptionIpn
no check-in.
A cada servida concluída:
1. A Enjoy.it termina de medir a dose
2. A Enjoy.it faz POST no seu consumptionIpn
3. Você verifica se já gravou aquele idTransaction
4. Se ainda não gravou, lança na conta do cliente
5. Só então responde 2xx
O passo 3 é obrigatório. Sem ele, uma reentrega cobra o cliente duas vezes — e reentregas acontecem: se você não responder com sucesso, a Enjoy.it reenvia o mesmo consumo até 5 vezes, a cada 15 minutos.
A sua resposta de sucesso no passo 5 também dá a baixa da transação. Em webhook não existe
chamada de confirmação a fazer: responder 2xx já marca o consumo como processado. É exatamente por
isso que o passo 5 vem depois do 4 — responder antes de gravar dá baixa em um consumo que você não
lançou, e ele não será reenviado.
Ver o contrato do webhook e a política de reentrega
Opção B — Consulta (você pergunta)
Não informe consumptionIpn. Consulte as transações do cliente em dois momentos:
-
Ao abrir o extrato para o operador ou para o cliente;
-
Imediatamente antes do fechamento, para a conferência final.
Use o idTransaction para não importar a mesma transação duas vezes.
Dar baixa nas transações importadas (ack)
Toda transação carrega uma marca de "já processada pelo parceiro". Nem toda integração precisa se preocupar com ela:
| Forma de recebimento | Precisa dar baixa? |
|---|---|
| Webhook | Não. A baixa é automática: responder com sucesso (2xx) à notificação já confirma a transação |
| Consulta por comanda, RFID ou Wallet | Sim. Depois de gravar cada transação, chame o endpoint de confirmação |
| Varredura por transações não confirmadas | Sim. É a baixa que tira a transação da próxima varredura |
Se você recebe por webhook, esta seção não se aplica.
O motivo de a baixa existir na consulta: ela devolve o extrato inteiro, sempre. A API não sabe o que você já lançou — quem controla isso é você.
Depois de gravar a transação no seu sistema, confirme o processamento:
PUT /places/{idPlace}/transactions/users/{uid}/date/{createdAt}/acknowledge
{
"uid": "5FS6DS0BDERIWG9QL6ojfuLedg23",
"createdAt": "2026-08-02T19:43:29.416Z",
"acknowledgeReference": "lancamento-pdv-55421"
}
| Campo | Observação |
|---|---|
uid e createdAt | Repetem os valores da URL, por validação |
acknowledgeReference | Opcional. Aponte para o registro criado no seu sistema — é o que permite rastrear depois qual lançamento do PDV corresponde àquele consumo |
Confirme apenas depois de persistir com sucesso. A confirmação tira a transação da lista de pendências, e uma baixa dada cedo demais esconde um consumo que nunca foi lançado.
Ver a referência de confirmação
Varrer o que ainda não foi processado
Com as baixas em dia, você ganha um segundo caminho: perguntar à Enjoy.it o que ainda falta lançar, sem varrer comanda por comanda.
GET /places/{idPlace}/transactions/unacknowledged?startAt={data}&finishAt={data}&limit=100
Devolve as transações da loja que você ainda não confirmou. Serve para dois usos diferentes:
| Uso | Como funciona |
|---|---|
| Importação por varredura | Em vez de consultar cliente a cliente, o seu sistema varre as pendências da loja de tempos em tempos e lança o que apareceu |
| Rede de segurança | Uma rotina periódica que recupera o que escapou da importação normal |
A varredura é uma alternativa válida quando o seu sistema não precisa de tempo real e prefere um
processo em lote a chamadas espalhadas pelas telas. Sem startAt e finishAt, o padrão é buscar os
últimos três dias; limit e cursor paginam o resultado.
A baixa é o que faz a varredura funcionar. Sem confirmar o que processou, a mesma transação volta em todas as varreduras seguintes e a lista só cresce.
Entre uma varredura e a próxima, o cliente pode ter servido mais chope. Se ele pedir a conta nesse intervalo, o consumo não estará lançado.
Mesmo usando varredura, mantenha a consulta ao extrato do cliente ao exibir a conta e antes do pagamento. É esse par de consultas que garante que ninguém vai embora com consumo em aberto.
No pré-pago, o consumo também mexe no saldo
Nos dois modelos você precisa dos consumos para fechar a conta. No pré-pago existe um segundo motivo: cada chope servido debita o saldo do cliente na Enjoy.it, e o seu sistema precisa conhecer esse débito antes de autorizar uma compra fora da Enjoy.it — senão o mesmo dinheiro é gasto duas vezes.
Por isso, em pré-pago por consulta, a importação dos chopes acontece também no momento em que o cliente pede algo ao garçom, e não só no extrato e no fechamento.
Próximo passo
Volte para o detalhamento do seu modelo: pós-pago ou pré-pago.