Escolha sua integração
Não existe uma integração só. Existem combinações, e você precisa fechar três decisões antes de escrever código. Esta página faz as três perguntas, na ordem, com uma resposta padrão para cada uma.
Se você quiser colocar a "mão na massa", o caminho mais simples é:
Comanda + pós-pago + consulta na API. Não exige leitor de cartão no caixa, não exige controle de saldo e não exige que o seu sistema esteja na nuvem. São três chamadas: abrir, consultar e fechar.
Pergunta 1 — Como o cliente é identificado na torneira?
O cliente precisa de algo que a torneira reconheça. Escolha o que combina com a sua operação:
| Escolha | Marque esta opção se... | Endpoints |
|---|---|---|
| Comanda (padrão) | O cliente recebe um cartão com número impresso e o seu caixa não tem leitor de cartão | Comandas |
| RFID / NFC | O seu caixa já tem leitor e você prefere trabalhar com o código do chip | RFID |
| QR Code | O atendimento acontece em totem de autoatendimento, sem cartão físico | QR Code |
| Wallet | O cliente usa o seu aplicativo e é identificado por um código do seu sistema | Wallet |
Por que comanda é o padrão: você manda o número impresso, 006, e a Enjoy.it descobre sozinha
qual é o chip daquele cartão. Nenhum hardware novo no caixa, nenhuma tela nova para o operador.
Comanda e RFID são o mesmo cartão, vistos de formas diferentes: um pelo número impresso, outro pelo chip. Se você tiver dúvida entre os dois, comece por comanda — o cartão continua sendo o mesmo.
Pergunta 2 — O cliente paga antes ou depois?
Essa escolha depende da regra comercial da loja e de como o seu PDV já trabalha hoje.
Pós-pago (mais simples)
O cliente consome à vontade e paga tudo no fim, como uma comanda tradicional de bar.
- Você não gerencia saldo. É a razão de ser mais simples.
- A Enjoy.it acumula os consumos e o seu PDV cobra o total no fechamento.
- Risco da operação: um cliente pode consumir e sair sem pagar — o mesmo risco que já existe hoje com qualquer comanda aberta.
Pré-pago
O cliente coloca crédito antes e só consome enquanto tiver saldo.
- Você gerencia saldo, e ele precisa estar sincronizado dos dois lados.
- Toda recarga tem que ser informada à Enjoy.it, senão o cliente não consegue servir.
- Toda compra feita fora da Enjoy.it (comida, produtos) precisa atualizar o saldo disponível, senão o cliente gasta duas vezes o mesmo dinheiro.
| Pós-pago | Pré-pago | |
|---|---|---|
| Controla saldo | Não | Sim |
| Chamadas obrigatórias | 3 | 5 |
| Risco de calote | Existe | Não existe |
| Risco de consumo acima do saldo | Não se aplica | Existe, se o saldo não for sincronizado |
| Esforço de implementação | Menor | Maior |
Ele não tem saldo para administrar, e é o modelo em que menos coisa pode sair errada. Migrar para pré-pago depois é possível: as chamadas de abertura, consulta e fechamento continuam iguais, você só acrescenta recarga e sincronização de saldo.
Pergunta 3 — Como os chopes chegam até o seu sistema?
Esta é a pergunta que mais confunde, e ela não é sobre preferência. É sobre onde o seu sistema está instalado.
Responda uma coisa só: o seu sistema tem um endereço público na internet, do tipo
https://..., acessível de fora da loja?
- Se a resposta for sim, escolha webhook. O seu sistema roda em um servidor na nuvem, então a Enjoy.it consegue alcançá-lo: ela avisa o seu sistema a cada chope servido.
- Se a resposta for não, escolha consulta. O seu sistema roda em um micro ou servidor dentro da loja, então quem inicia a conversa é você: pergunte à Enjoy.it quando o operador abrir o extrato e de novo antes de fechar a conta.
Comparação
| Webhook | Consulta na API | |
|---|---|---|
| Quem inicia a conversa | A Enjoy.it chama você | O seu sistema chama a Enjoy.it |
| Exige endereço público HTTPS | Sim | Não |
| Serve para PDV instalado na loja | Não | Sim |
| Quando o chope aparece na conta | Segundos após a servida | Quando você consultar |
| O que você implementa | Um endereço que recebe POST | Chamadas GET nos momentos certos |
Se você escolheu webhook
Informe a URL no campo consumptionIpn na abertura da comanda. A cada servida concluída, a Enjoy.it
envia um POST com o consumo, e o seu sistema responde 2xx depois de gravar.
A sua resposta de sucesso serve de confirmação: ela dá a baixa da transação automaticamente, sem nenhuma chamada extra da sua parte.
Se o seu sistema não responder com sucesso, a Enjoy.it reenvia o mesmo consumo até 5 vezes, com intervalo de 15 minutos entre as tentativas, e para assim que receber uma resposta de sucesso.
Duas consequências práticas:
- Uma indisponibilidade curta se resolve sozinha, sem intervenção.
- Como as tentativas são espaçadas em 15 minutos, uma falha durante o atendimento pode não se recuperar a tempo do fechamento — o cliente vai embora antes da reentrega.
Webhook não substitui a conferência final. Esgotadas as 5 tentativas, o consumo não é reenviado. Mesmo usando webhook, consulte as transações uma última vez antes de fechar a conta e mantenha uma rotina de recuperação com transações não confirmadas.
Se você escolheu consulta
Não informe consumptionIpn. Consulte as transações em dois momentos obrigatórios:
- Quando o operador abrir o extrato do cliente.
- Imediatamente antes de fechar a conta.
Use o idTransaction para não importar a mesma transação duas vezes e, depois de gravar cada
transação, dê baixa nela com o endpoint de confirmação. É essa baixa que permite depois perguntar
à Enjoy.it apenas o que ainda falta lançar, em vez de reprocessar o extrato inteiro.
Quem não precisa de tempo real pode inclusive inverter a estratégia e importar por varredura, lendo periodicamente as transações não confirmadas da loja — sem deixar de consultar o extrato do cliente no fechamento.
Ver como dar baixa e varrer pendências
Resumo da sua escolha
Preencha e leve para a homologação:
| Decisão | Sua resposta | Onde está documentado |
|---|---|---|
| Identificação | Comanda / RFID / QR Code / Wallet | Referência da API |
| Modelo financeiro | Pós-pago / pré-pago | Pós-pago · Pré-pago |
| Recebimento dos consumos | Webhook / consulta | Receber os consumos |
O que cada combinação exige de você
| Combinação | Chamadas que você implementa |
|---|---|
| Pós-pago + consulta | checkin, GET transactions, PUT acknowledge, checkout |
| Pós-pago + webhook | checkin, checkout, GET transactions na conferência final, e um endereço seu que recebe os consumos |
| Pré-pago + consulta | As de pós-pago + recharges + PUT balance |
| Pré-pago + webhook | As de pré-pago + o endereço que recebe os consumos |
É comum começar por consulta e evoluir para webhook quando o parceiro migra para a nuvem. As chamadas de abertura, extrato e fechamento não mudam — você só passa a receber os consumos em vez de buscá-los. Qualquer mudança de modelo deve ser validada de novo na homologação, para garantir que nenhum lançamento seja duplicado durante a virada.
Próximo passo
Com as três respostas definidas, vá para a Jornada ponta a ponta e veja em que momento do atendimento cada chamada acontece.