Jornada ponta a ponta

Esta página responde a pergunta central de quem está implementando: em que momento do atendimento eu chamo cada API?

A sequência é a mesma para comanda, RFID e Wallet — muda só o caminho do endereço. O QR Code tem particularidades, descritas no fim da página.

O que a Enjoy.it te entrega antes de começar

Isto é configuração da integração, definida na homologação:

Você recebe	Exemplo	Para quê
x-api-key	abc123...	Autenticar as chamadas
idPlace	P-PDV	Identificar cada loja autorizada
Modelo financeiro	postpaid ou prepaid	Definir se há saldo a controlar
Forma de recebimento	Webhook, consulta ou os dois	Definir como os chopes chegam
Modo direct	Habilitado ou não	Só se o seu app abrir torneiras sozinho

A linha do tempo de um atendimento

Um atendimento tem três momentos:

1. Chegada — o caixa abre a comanda (checkin) e, só no pré-pago, registra o crédito que o cliente pagou (recharges).
2. Consumo (repete quantas vezes o cliente quiser) — o cliente serve o chope e ele entra na conta pelo caminho que você escolheu: webhook ou consulta.
3. Saída — o caixa confere a conta (GET transactions) e bloqueia a comanda (checkout).

Passo a passo

Etapa	O que o cliente faz	O que o seu sistema faz	API
1. Identificação	Apresenta a comanda, o cartão ou entra no app	Consulta se já existe sessão aberta, quando precisar	GET do identificador
2. Abertura	Informa os dados no caixa ou no totem	Abre a sessão com o plano, o cliente e, se houver, as URLs de webhook	POST .../checkin
3. Crédito (só pré-pago)	Paga o valor inicial	Registra o crédito depois que o pagamento for aprovado	POST .../recharges
4. Liberação	Encosta a comanda na torneira	Nada. A Enjoy.it reconhece sozinha	Nenhuma
5. Consumo	Serve o chope	Nada. A Enjoy.it mede e cria a transação ao fim da servida	Nenhuma
6. Conciliação	Continua consumindo ou pede o extrato	Recebe o consumo por webhook ou consulta, grava sem duplicar e dá baixa no que processou	consumptionIpn — a baixa é a sua resposta de sucesso — ou GET .../transactions seguido de PUT .../acknowledge
7. Extras	Compra outro produto, recarrega ou pede estorno	Registra o produto, a recarga, o saldo novo ou o estorno	POST .../transactions, POST .../recharges, PUT .../balance, DELETE .../transactions/{idTransaction}
8. Saída	Vai embora e devolve a comanda	Faz a conferência final, cobra e bloqueia a comanda	GET .../transactions e depois POST .../checkout

Onde isso encaixa nas suas telas

Tela do seu PDV	Chamada que você acrescenta
Abertura de comanda / mesa	POST .../checkin, depois de identificar o cliente
Recebimento de crédito (só pré-pago)	POST .../recharges, depois da aprovação do pagamento
Consulta de extrato / espelho da conta	GET .../transactions antes de montar a tela
Rotina que grava o consumo no seu banco	PUT .../acknowledge para dar baixa — só em integrações por consulta; no webhook a baixa é a sua resposta de sucesso
Venda de outros produtos	POST .../transactions (opcional); no pré-pago, também PUT .../balance
Fechamento de conta	GET .../transactions para conferência e, após o pagamento, POST .../checkout
Cancelamento de item	DELETE .../transactions/{idTransaction}
Troca de comanda danificada	PUT /places/{idPlace}/tabs com o número antigo e o novo

Só avance quando

Uma checagem por etapa, para não deixar o cliente na mão:

Etapa	Só siga adiante quando
Abertura	A resposta for 201. Entregar a comanda antes disso significa cliente parado na torneira
Crédito	A recarga responder 201. Só então mostre o saldo novo ao cliente
Conciliação	O consumo estiver gravado no seu banco, sem duplicidade
Saída	O checkout responder 200. Só então libere o cliente e reutilize a comanda

O que significa encerrar

O encerramento acontece quando o cliente vai embora. Não é apenas fechar a conta no PDV: é preciso bloquear a comanda na Enjoy.it para que ela não libere outra torneira depois da saída.

A ordem importa:

1. O cliente avisa que vai sair.
2. Recolha a comanda ou o cartão físico. Em Wallet, tire do app a opção de abrir torneiras.
3. Consulte e importe os últimos consumos.
4. Confira o saldo ou cobre o valor pós-pago.
5. Chame o checkout usando exatamente o mesmo identificador usado na abertura.
6. Aguarde 200 OK.
7. Só então conclua o atendimento e devolva a comanda ao estoque de cartões.

Pagamento não é encerramento

Mesmo com pagamento recebido, a comanda continua liberando chope até o checkout ser concluído.

E não chame o checkout antes da conferência final: uma servida terminada poucos segundos antes da saída pode ainda não ter sido importada pelo seu sistema. Recolher o cartão antes de conferir resolve essa corrida — sem o cartão, ninguém serve mais nada.

Qual endpoint usar em cada caso

Troque {idPlace} e o identificador entre chaves pelos valores reais.

Operação	Comanda	RFID	Wallet
Consultar	GET /places/{idPlace}/tabs/{idTab}	GET /places/{idPlace}/rfids/{rfid}	GET /places/{idPlace}/customers/{reference}
Abrir sessão	POST /places/{idPlace}/tabs/{idTab}/checkin	POST /places/{idPlace}/rfid/{rfid}/checkin	POST /places/{idPlace}/customers/{reference}/checkin
Registrar recarga	POST /places/{idPlace}/tabs/{idTab}/recharges	POST /places/{idPlace}/rfid/{rfid}/recharges	POST /places/{idPlace}/customers/{reference}/recharges
Consultar consumos	GET /places/{idPlace}/tabs/{idTab}/transactions	GET /places/{idPlace}/rfid/{rfid}/transactions	GET /places/{idPlace}/customers/{reference}/transactions
Registrar produto externo	POST /places/{idPlace}/tabs/{idTab}/transactions	POST /places/{idPlace}/rfid/{rfid}/transactions	POST /places/{idPlace}/customers/{reference}/transactions
Atualizar saldo	PUT /places/{idPlace}/tabs/{idTab}/balance	PUT /places/{idPlace}/rfid/{rfid}/balance	PUT /places/{idPlace}/customers/{reference}/balance
Bloquear na saída	POST /places/{idPlace}/tabs/{idTab}/checkout	POST /places/{idPlace}/rfid/{rfid}/checkout	POST /places/{idPlace}/customers/{reference}/checkout

Particularidades do QR Code

O QR Code é criado pela própria API — não é um cartão que já existe na loja. Por isso a sequência é um pouco diferente.

Momento	Chamada	Resultado
Criar a sessão	POST /places/{idPlace}/qrcodes/checkin	201 com o novo qrcode
Creditar pagamento	POST /places/{idPlace}/qrcodes/{qrCode}/recharges	201 com a recarga registrada
Entregar ao cliente	Exibir na tela ou POST /places/{idPlace}/qrcodes/{qrCode}/methods/whatsapp	O cliente recebe o código
Conciliar	Preferencialmente consumptionIpn; havendo exatamente uma credencial ativa para o telefone, GET /places/{idPlace}/transactions/users?method=phone&phone={phone}	Consumo gravado sem duplicidade
Invalidar na saída	DELETE /places/{idPlace}/qrcodes?phone={phone}	Os códigos anteriores param de funcionar

QR Code não tem checkout

Na API atual, o QR Code não possui um endpoint de checkout equivalente ao de comanda, RFID e Wallet.

Quando for obrigatório impedir novos consumos na saída, invalide os códigos pelo telefone e não entregue ao cliente o novo código que vem na resposta. Esse novo código preserva saldo e bônus; o tratamento desse valor deve ser combinado na homologação.

Próximo passo

Veja como trazer os chopes para o seu sistema em Receber os consumos e dar baixa, e o detalhamento do modelo que você escolheu: pós-pago ou pré-pago. Para totens e aplicativos, veja Totens e Wallets.