Integração pós-paga

No pós-pago o cliente consome primeiro e paga no fim, como uma comanda tradicional de bar. Não há saldo para controlar: a Enjoy.it vai acumulando os consumos e o seu PDV cobra o total no fechamento.

É o modelo mais simples e o recomendado para quem está começando.

O resumo: três chamadas

1. Abrir — POST .../checkin.
2. Consumir — nada seu aqui. A Enjoy.it reconhece a comanda, mede a dose e registra o consumo.
3. Fechar — GET .../transactions para a conferência final e POST .../checkout para bloquear a comanda.

Tudo o mais nesta página é detalhe dessas três chamadas.

A jornada do cliente

Momento	O que o cliente vive	O que o seu sistema faz	API
Chegada	Recebe a comanda no caixa	Verifica se já há sessão aberta, se precisar	GET do identificador
Abertura	Informa o nome e leva a comanda	Abre a sessão com plan: "postpaid"	POST .../checkin
Serviço	Encosta a comanda e serve	Nada. A leitura e a medição são da Enjoy.it	Nenhuma
Fim da servida	Vê o valor no totem	Recebe o webhook ou consulta, e lança na conta	consumptionIpn ou GET .../transactions
Novo consumo	Repete quantas vezes quiser	Continua conciliando, sem duplicar	Webhook ou consulta
Saída	Devolve a comanda e paga	Recolhe o cartão, confere, cobra e bloqueia a comanda	GET .../transactions, depois POST .../checkout

1. Abertura

Faça o check-in com o identificador que você escolheu:

• Check-in por comanda
• Check-in por RFID
• Check-in por Wallet

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

Campo	Observação
plan	Sempre postpaid neste fluxo
hasConsumptionLimit	false: o cliente serve à vontade
consumer.consumerReference	O código do cliente no seu sistema. É por ele que você reencontra o cliente na conciliação
consumptionIpn	Só se você escolheu webhook. Se for usar consulta, omita este campo

aviso

Só entregue a comanda depois de receber 201 Created. Uma resposta de erro significa que a sessão não foi aberta e o cliente ficaria parado na torneira sem entender o motivo.

2. Receber os consumos

Os chopes chegam ao seu sistema de uma de duas formas, definidas na escolha da integração:

Forma	O que você faz	Precisa dar baixa (ack)?
Webhook	Informa consumptionIpn no check-in e recebe um POST a cada servida	Não. A sua resposta de sucesso já confirma
Consulta	Chama GET .../transactions ao exibir o extrato e antes de fechar a conta	Sim, pelo endpoint de confirmação

Em qualquer uma delas, use o idTransaction para não lançar a mesma transação duas vezes.

O passo a passo de cada opção, a política de reentrega do webhook, o endpoint de baixa e a importação por varredura estão em Receber os consumos e dar baixa.

3. Encerramento

O encerramento começa quando o cliente avisa que vai embora — não quando o pagamento é aprovado.

1. Recolha a comanda ou o cartão físico
   (em Wallet: bloqueie novas aberturas de torneira no app)
2. GET .../transactions  -> conferência final
3. Lance o que faltar na conta
4. Cobre o cliente
5. POST .../checkout     -> a comanda é bloqueada
6. Aguarde 200 OK
7. Libere o cliente e devolva a comanda ao estoque

Endpoints de checkout:

• Checkout por comanda
• Checkout por RFID
• Checkout por Wallet

O checkout também aceita uma lista products com itens vendidos no seu PDV que ainda não foram enviados à Enjoy.it. Se você já registrou esses itens por POST .../transactions, não os repita aqui — seriam lançados duas vezes. Quando não houver nada a enviar, mande uma lista vazia:

{ "products": [] }

Recolher o cartão primeiro não é detalhe

Entre a sua conferência final e o checkout existe uma janela de alguns segundos. Se o cliente ainda estiver com a comanda na mão, ele pode tirar mais um chope nessa janela — e esse consumo não vai entrar na conta que você acabou de cobrar.

Recolher o cartão antes de conferir fecha essa janela fisicamente.

Erros comuns neste fluxo

Sintoma	Causa provável	Correção
Cliente consumiu depois de pagar	O checkout não foi chamado	Chame o checkout em toda finalização, inclusive nas canceladas pela metade
Consumo lançado em duplicidade	Falta de controle por idTransaction	Grave o identificador antes de lançar e ignore repetidos
Último chope não entrou na conta	Conferência feita antes da última servida	Recolha o cartão e consulte de novo imediatamente antes do checkout
4002 ao lançar um produto	A comanda já foi encerrada	Verifique o estado antes de lançar, ou lance antes do checkout
Cliente não consegue servir	O check-in falhou e ninguém percebeu	Só entregue a comanda após o 201

Próximo passo

Se a sua operação usa crédito antecipado, veja o fluxo pré-pago. Para totens e aplicativos, veja Totens e Wallets.