Integração pré-paga

No pré-pago o cliente paga antes e consome até o saldo acabar. A Enjoy.it só libera a torneira enquanto houver crédito disponível.

Em troca dessa segurança, você assume uma responsabilidade a mais: manter o saldo sincronizado.

O problema central: o mesmo dinheiro em dois lugares

O cliente tem R$ 100. Ele pode gastar esse dinheiro em dois lugares diferentes: na torneira (controlada pela Enjoy.it) e no seu PDV (comida, produtos, o que a loja vender).

Veja o que acontece quando ele recarrega R$ 100:

1. Na torneira, controlada pela Enjoy.it, o cliente tira R$ 60 de chope.
2. No seu PDV, ele compra R$ 50 de comida.
3. Total gasto: R$ 110 de um saldo de R$ 100.

Isso acontece se os dois lados não conversarem. Por isso, no pré-pago, além das três chamadas do pós-pago, existem mais duas:

Chamada extra	Quando
POST .../recharges	Sempre que o cliente colocar crédito
PUT .../balance	Sempre que o cliente gastar fora da Enjoy.it

A jornada do cliente

Momento	O que o cliente vive	O que o seu sistema faz	API
Chegada	Recebe a comanda	Consulta a sessão ou abre uma nova com limite	GET e POST .../checkin
Pagamento	Escolhe o valor e paga	Aguarda a aprovação e só então registra o crédito	POST .../recharges
Serviço	Encosta a comanda e serve	Nada. A Enjoy.it confere o saldo e libera ou recusa	Nenhuma
Fim da servida	Vê o volume e o valor debitados	Recebe ou consulta a transação para manter seu saldo conciliado	consumptionIpn ou GET .../transactions
Nova recarga	Paga mais	Registra apenas pagamentos aprovados	POST .../recharges
Compra no PDV	Compra comida ou produtos	Concilia os chopes, valida o saldo e atualiza o disponível	GET .../transactions e PUT .../balance
Saída	Vai embora e devolve a comanda	Conferência final, acerto do saldo e bloqueio	GET .../transactions, depois POST .../checkout

1. Abertura com saldo

{
  "plan": "prepaid",
  "hasConsumptionLimit": true,
  "balance": 120,
  "consumer": {
    "name": "Maria Silva",
    "consumerReference": "cliente-123"
  }
}

Campo	Observação
plan	Sempre prepaid neste fluxo
hasConsumptionLimit	true. É este campo que faz a torneira respeitar o saldo
balance	O crédito já disponível na abertura, em reais

O campo balance serve para crédito que já existe — um bônus, um pacote incluso na entrada, um saldo trazido de outro sistema. Quando o cliente estiver pagando naquele momento, prefira abrir a sessão e registrar o pagamento pelo endpoint de recarga: assim o meio de pagamento fica auditável no extrato.

aviso

Se hasConsumptionLimit ficar false em um fluxo pré-pago, a torneira libera consumo mesmo sem saldo. Esse é o erro que mais aparece em homologação de pré-pago.

2. Recargas

A ordem é obrigatória e não pode ser invertida:

1. Seu PDV pede o pagamento à maquininha / Pix
2. O pagamento é APROVADO
3. POST .../recharges com value e paymentMethod
4. 201 Created
5. Só agora o cliente vê o saldo novo na tela

Registrar a recarga antes da aprovação libera chope para um pagamento que pode ser recusado.

{
  "value": 50,
  "paymentMethod": "credit-card"
}

paymentMethod é opcional e aceita valores como debit-card, credit-card, cash ou on-the-house (cortesia).

Endpoints por identificador:

• Recarga por comanda
• Recarga por RFID
• Recarga por Wallet
• Recarga por QR Code

3. Receber os consumos

Cada chope servido debita o saldo do cliente na Enjoy.it. O seu sistema precisa conhecer esses débitos por dois motivos: fechar a conta corretamente e saber quanto o cliente ainda tem antes de autorizar uma compra fora da Enjoy.it.

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 no extrato, antes de cada compra externa e antes do fechamento	Sim, pelo endpoint de confirmação

Repare na diferença em relação ao pós-pago: aqui existe um terceiro momento de consulta, antes de autorizar qualquer venda fora da Enjoy.it. Sem ele, você autoriza uma compra usando um saldo que já foi gasto na torneira.

Em qualquer uma das formas, 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.

4. Compras fora da Enjoy.it

Quando o cliente compra comida ou produtos no seu PDV usando o mesmo crédito, o saldo disponível para chope precisa diminuir.

Se você recebe por webhook

1. Os chopes já chegam sozinhos e você os lança
2. O cliente pede um lanche de R$ 30
3. Você valida com o saldo que já conhece
4. Registra a venda no seu PDV
5. PUT .../balance com o novo saldo

Se você recebe por consulta

O passo extra é no início: você não sabe quanto o cliente já bebeu até perguntar.

1. GET .../transactions  -> importa os chopes ainda não lançados
2. Recalcula o saldo real do cliente
3. Verifica se dá para pagar o lanche de R$ 30
   - Não dá? Recuse a venda ou peça recarga
4. Registra a venda no seu PDV
5. PUT .../balance com o novo saldo

Pular o passo 1 é o caminho direto para o cliente gastar mais do que tem: ele pode ter bebido R$ 80 desde a sua última consulta.

Ao importar cada chope no passo 1, dê baixa na transação — veja dar baixa nas transações importadas.

Como atualizar o saldo

O endpoint aceita as duas formas:

{
  "balance": 75.5
}

Forma	Chamada	Quando usar
Absoluta	PUT .../balance	Você calculou o saldo final e quer que ele valha. Mais previsível
Relativa	PUT .../balance?relative=true	Você quer somar ou subtrair do saldo atual

Prefira a forma absoluta sempre que conseguir calcular o total: ela corrige divergências em vez de acumulá-las.

Opcional: registrar a venda em vez de só ajustar o número

Em vez de recalcular o saldo por fora, você pode registrar a venda como uma transação na Enjoy.it:

POST /places/{idPlace}/tabs/{idTab}/transactions

Esse endpoint lança o item e já sensibiliza o saldo, dispensando o PUT .../balance naquela venda. Como efeito colateral útil, o extrato da Enjoy.it passa a refletir a conta inteira do cliente, e não só o chope.

Não é obrigatório: se o seu sistema já controla o saldo e prefere apenas informar o novo valor, PUT .../balance continua válido. Escolha um dos dois caminhos por venda — usar os dois na mesma venda desconta duas vezes.

Ver o modelo de produto externo

Alternativa: deixar a Enjoy.it perguntar o saldo (balanceIpn)

Se o seu sistema não puder atualizar o saldo a cada venda, existe o caminho inverso: informe um balanceIpn no check-in e a Enjoy.it consulta o seu sistema para saber o saldo disponível antes de liberar a torneira.

	Atualizar o saldo (PUT .../balance)	Ser consultado (balanceIpn)
Onde vive o saldo verdadeiro	Nos dois lados, sincronizados	Só no seu sistema
Você precisa sincronizar	Sim, a cada venda externa	Não
Impacto no atendimento	Nenhum	O cliente espera a sua resposta na torneira
Recomendação	Preferível	Válido quando não há alternativa

O custo do balanceIpn é sentido pelo cliente

Essa consulta entra no caminho crítico do atendimento: toda vez que o cliente encosta o cartão na torneira, a liberação depende de uma chamada ao seu sistema. Com várias torneiras e movimento, são muitas chamadas, e qualquer lentidão vira fila na chopeira.

Use balanceIpn quando não houver como sincronizar o saldo. Nesse caso, trate esse endereço como crítico: resposta rápida, alta disponibilidade e monitoramento.

Ver o contrato do balanceIpn

5. Encerramento

1. Recolha a comanda ou o cartão
2. GET .../transactions  -> conferência final
3. Recalcule o saldo e persista o extrato
4. Acerte a devolução de saldo, se a regra da loja previr
5. POST .../checkout
6. Aguarde 200 OK

Endpoints: comanda, RFID ou Wallet.

Erros comuns neste fluxo

Sintoma	Causa provável	Correção
Cliente consome além do saldo	hasConsumptionLimit está false	Abra a sessão com true
Cliente gasta o mesmo dinheiro duas vezes	Compra externa sem PUT .../balance	Atualize o saldo após toda venda no seu PDV
Saldo do PDV diferente do saldo da Enjoy.it	Uso de saldo relativo com chamadas repetidas	Migre para saldo absoluto e reconcilie pelo extrato
Cliente não consegue servir após pagar	Recarga não registrada ou registrada antes da aprovação	Registre a recarga logo após o 201 do pagamento
Chope liberado com pagamento recusado	Recarga registrada antes da aprovação	Inverta a ordem: aprova, depois registra

Valide concorrência na homologação

Um cliente pode estar servindo chope no mesmo instante em que o caixa registra um lanche. Teste esse cenário antes de ir para produção: é onde as divergências de saldo aparecem.

Próximo passo

Para totens de autoatendimento e recarga sem operador, veja Totens e Wallets.