Totens, QR Code e Wallets
As páginas anteriores assumem um operador no caixa. Esta página cobre os casos em que não há operador: um totem de autoatendimento onde o próprio cliente se cadastra e paga, ou um aplicativo onde ele acompanha o consumo pelo celular.
A lógica continua a mesma — abrir, consumir, conciliar, encerrar. Muda quem aperta os botões.
Totem com QR Code
Aqui não existe cartão físico: o QR Code é criado pela API e entregue ao cliente na hora.
Crie o QR Code, receba o pagamento, registre a recarga e só então mostre o código ao cliente.
Um QR Code entregue antes da recarga é uma credencial sem saldo: o cliente vai até a torneira, não consegue servir e volta reclamar no totem.
Fluxo de um cliente novo
| Momento | O que o cliente faz | Chamada do totem | Antes de seguir |
|---|---|---|---|
| Cadastro | Informa nome, telefone e documento | POST /places/{idPlace}/qrcodes/checkin | Guarde o qrcode do 201 sem exibir |
| Pagamento | Escolhe o valor e paga | Primeiro a maquininha ou Pix do parceiro; depois de aprovado, POST /places/{idPlace}/qrcodes/{qrCode}/recharges | Continue só após o 201 da recarga |
| Entrega | Escolhe ver na tela, imprimir ou receber no WhatsApp | Para WhatsApp: POST /places/{idPlace}/qrcodes/{qrCode}/methods/whatsapp | Confirme e encerre a tela |
| Consumo | Apresenta o código na torneira | Nenhuma. A Enjoy.it registra a servida | Receba por webhook ou consulte pelo telefone |
Ver requests e responses de QR Code
Recarga de um QR Code existente
1. O totem lê o QR Code que o cliente já tem
2. O cliente escolhe o valor
3. O totem processa o pagamento (fora da API Enjoy.it)
4. Pagamento APROVADO
5. POST /places/{idPlace}/qrcodes/{qrCode}/recharges
6. 201 Created -> só agora o totem exibe o novo saldo
Reimpressão: o cliente perdeu o código
Antes de reemitir, é preciso confirmar que a pessoa é mesmo a dona do código. A confirmação é feita por um código enviado ao WhatsApp dela:
1. GET /places/{idPlace}/customers?phone={phone} -> acha o cliente
2. POST /places/{idPlace}/customers/{uid}/codes/methods/whatsapp
-> envia o código
3. O cliente informa no totem o código recebido
4. POST /places/{idPlace}/customers/{uid}/codes/{code} -> valida
5. Confirmado: reenvie o QR Code
Cancelamento
Para invalidar os códigos de um cliente — na saída ou ao substituir um código perdido:
DELETE /places/{idPlace}/qrcodes?phone={phone}
Os códigos que estavam com o cliente param de liberar consumo. A resposta traz um novo qrcode,
com balance e bonus consolidados.
| Sua intenção | O que fazer com o novo código da resposta |
|---|---|
| Substituir um código perdido | Entregue o novo código e remova os anteriores do app ou do totem |
| Encerrar o acesso na saída | Não exiba nem envie. O saldo preservado segue a regra comercial combinada |
Totem com cartão físico
O cliente chega ao totem com um cartão que já existe. O totem consulta antes de agir, para não abrir uma comanda que já está aberta:
| Momento | Com número de comanda | Com leitura RFID |
|---|---|---|
| Ler a credencial | Capture idTab | Capture rfid |
| Consultar o estado | GET /places/{idPlace}/tabs/{idTab} | GET /places/{idPlace}/rfids/{rfid} |
| Abrir, se necessário | POST /places/{idPlace}/tabs/{idTab}/checkin | POST /places/{idPlace}/rfid/{rfid}/checkin |
| Mostrar extrato | GET /places/{idPlace}/tabs/{idTab}/transactions | GET /places/{idPlace}/rfid/{rfid}/transactions |
| Registrar pagamento aprovado | POST /places/{idPlace}/tabs/{idTab}/recharges | POST /places/{idPlace}/rfid/{rfid}/recharges |
Se a consulta mostrar uma sessão já aberta, não repita o check-in. Exiba o saldo e ofereça recarga ou extrato, conforme a operação.
Wallet ou aplicativo próprio
Wallet é o modelo sem cartão e sem QR Code: o cliente é identificado por uma reference — um código
estável do seu sistema, como o id do usuário no seu app. Ele não muda durante a jornada.
É o modelo para quem já tem um aplicativo e quer colocar o chope dentro dele. O cliente entra com a conta que já usa, e o app passa a mostrar saldo e extrato e — se a operação permitir — a abrir a torneira, lendo um código afixado nela ou tocando em um botão na própria tela. Nada de cartão para entregar, código para exibir ou fila no caixa: a credencial é a conta que o cliente já tem no seu sistema.
| Ação no aplicativo | Endpoint |
|---|---|
| Abrir a sessão | POST /places/{idPlace}/customers/{reference}/checkin |
| Exibir saldo e estado | GET /places/{idPlace}/customers/{reference} |
| Exibir extrato | GET /places/{idPlace}/customers/{reference}/transactions |
| Registrar crédito aprovado | POST /places/{idPlace}/customers/{reference}/recharges |
| Registrar compra externa | POST /places/{idPlace}/customers/{reference}/transactions |
| Sincronizar saldo | PUT /places/{idPlace}/customers/{reference}/balance |
| Montar o catálogo de chopes para o cliente escolher | GET /places/{idPlace}/taps |
| Detalhar a torneira que o cliente escolheu | GET /places/{idPlace}/taps/{idTap} |
| Abrir uma torneira pelo app | POST /places/{idPlace}/customers/{reference}/taps/{idTap}/open |
| Encerrar a sessão | POST /places/{idPlace}/customers/{reference}/checkout |
A listagem de torneiras é o que alimenta o cardápio dentro do app: cada torneira vem com nome, preço
por mililitro, volume padrão do copo e, quando há barril conectado, a cervejaria e a marca com
descrição, teor alcoólico, IBU e imagem. Use kegPresent e lastHardwarePingAt para não oferecer ao
cliente uma torneira sem barril ou fora do ar.
Ver os campos da listagem.
Abrir a torneira pelo aplicativo
Normalmente o cliente se identifica no equipamento, e o app só acompanha saldo e extrato. Deixar
o app abrir a torneira diretamente é um recurso à parte, o modo direct, que precisa ser
habilitado pela Enjoy.it na configuração da integração. Sem essa habilitação a chamada responde
403.
A chamada é sempre a mesma — POST /places/{idPlace}/customers/{reference}/taps/{idTap}/open. O que
muda é como o seu app descobriu o idTap:
| Como o cliente escolhe | De onde vem o idTap | Quando usar |
|---|---|---|
| Lê um código na torneira | Do código que você afixa em cada torneira, carregando o idTap | Muitas torneiras: o cliente aponta o celular para a que está na frente dele, sem escolher da lista |
| Toca em um botão no app | De GET /places/{idPlace}/taps, que traz nome, barril e preço de cada torneira | Poucas torneiras, ou quando o app já exibe o menu de chopes |
Nos dois casos a sessão da Wallet precisa já estar aberta: o endpoint libera a torneira para uma credencial existente, não faz o check-in por você.
Trate na tela do app as falhas 422 do equipamento — torneira offline, sem barril, barril acabado,
saldo insuficiente. São elas que o cliente vê quando nada acontece na torneira.
O aplicativo de celular nunca deve carregar a x-api-key. Ele chama o seu backend, e o seu
backend chama a Enjoy.it. Veja Autenticação.