Wallet

Use estes endpoints para integrar aplicativos e carteiras digitais sem depender de cartão físico.

Toda operação aqui é identificada pela reference — o código do cliente no seu sistema. Para localizar uma pessoa, verificar a identidade dela ou consultar consumo consolidado, use Consumidores.

Resumo

Método	Endpoint	Finalidade
GET	/places/{idPlace}/customers/{reference}	Consultar Wallet
POST	/places/{idPlace}/customers/{reference}/checkin	Abrir Wallet
PUT	/places/{idPlace}/customers/{reference}	Alterar consumidor
GET	/places/{idPlace}/customers/{reference}/transactions	Consultar transações
POST	/places/{idPlace}/customers/{reference}/transactions	Registrar produto externo
DELETE	/places/{idPlace}/customers/{reference}/transactions/{idTransaction}	Estornar transação
POST	/places/{idPlace}/customers/{reference}/recharges	Registrar recarga
PUT	/places/{idPlace}/customers/{reference}/balance	Atualizar saldo
POST	/places/{idPlace}/customers/{reference}/checkout	Encerrar Wallet
POST	/places/{idPlace}/customers/{reference}/reset	Reiniciar Wallet

Parâmetros e erros comuns

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
idPlace	string	Sim	Código do estabelecimento. Precisa estar no escopo da sua chave
reference	string	Sim	Código do consumidor no seu sistema. Ver o aviso abaixo

A reference precisa ser estável para sempre

A Enjoy.it não guarda a reference como um campo: ela deriva a credencial a partir da combinação do seu código de parceiro + reference + idPlace. A mesma reference sempre aponta para a mesma credencial, e uma reference diferente cria outra.

Consequência prática: se o seu sistema mudar o código de um cliente — por recadastro, migração de base ou troca de prefixo —, ele perde o acesso ao saldo e ao extrato que estavam na credencial anterior. Escolha um identificador que nunca muda.

Todos os caminhos desta página usam reference

Nenhum endpoint aqui espera o uid da Enjoy.it. Os que usam uid — pesquisa, verificação de identidade e relatórios — estão em Consumidores.

Erros comuns

Status	Código	Mensagem	Quando acontece
400	—	validação do payload	Campo obrigatório ausente ou com tipo errado
403	—	Not authorized to interact with this place (idPlace)	A chave não tem acesso a esse estabelecimento
404	4042	RFID card not found in userRfid table.	Não existe Wallet aberta para essa reference
423	4231	Place suspended!	O estabelecimento está suspenso

Consultar Wallet

Retorna o estado atual da Wallet e o consumidor vinculado a ela.

GET /places/{idPlace}/customers/{reference}

Resposta 200

Campo	Tipo	Descrição
uid	string	Identificador do consumidor na Enjoy.it
rfid	string	Credencial derivada da reference
idTab	string	Número de comanda vinculado, quando houver
plan	string	prepaid ou postpaid
status	string	Estado da credencial. enable indica que ela libera consumo
accountBalance	number	Saldo disponível, em reais
hasConsumptionLimit	boolean	Se true, a torneira respeita o saldo
createdAt	string	Data de abertura da sessão, em ISO 8601
consumerReference	string	Código do consumidor no seu sistema
consumptionIpn	string	Webhook de consumo configurado nesta sessão
balanceIpn	string	Endereço consultado para obter o saldo
openTapIpn	string	Webhook de mudança de estado da torneira
broughtGlass	boolean	Se o consumidor trouxe o próprio copo
glassPrice	number	Valor do copo, quando aplicável
qrCode	string	QR Code vinculado, quando houver
customer	objeto	Dados do consumidor: uid, name, document, cellphone, consumerReference, email, gender, birthdate, region

{
  "accountBalance": 60,
  "createdAt": "2026-08-02T19:43:29.416Z",
  "hasConsumptionLimit": true,
  "consumerReference": "cliente-123",
  "plan": "prepaid",
  "status": "enable",
  "uid": "5FS6DS0BDERIWG9QL6ojfuLedg23",
  "customer": {
    "name": "Maria Silva",
    "consumerReference": "cliente-123"
  }
}

Só os erros comuns.

Abrir uma Wallet

Cria a sessão do consumidor e libera o consumo.

POST /places/{idPlace}/customers/{reference}/checkin

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
plan	string	Sim	prepaid ou postpaid
consumer	objeto	Sim	Dados do consumidor. Ver tabela abaixo
hasConsumptionLimit	boolean	Não	Em pré-pago use true, senão a torneira libera sem saldo
balance	number	Não	Saldo inicial em reais
bonus	number	Não	Crédito de cortesia em reais
consumptionIpn	string	Não	URL chamada a cada consumo. Informe apenas se você usa webhook
balanceIpn	string	Não	URL consultada pela Enjoy.it para obter o saldo antes de liberar a torneira
broughtGlass	boolean	Não	Indica que o consumidor trouxe o próprio copo
glassPrice	number	Não	Valor do copo, quando aplicável
reopenTab	string	Não	Reabre uma sessão anterior em vez de criar uma nova

Campos de consumer:

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome apresentado no totem e nos relatórios
consumerReference	string	Sim neste endpoint	Ver aviso abaixo
cellphone	string	Não	Telefone, preferencialmente com +55
document	string	Não	Documento, apenas dígitos
email	string	Não	E-mail
gender	string	Não	male, female ou other
birthdate	string	Não	Data de nascimento
showLeaderboard	boolean	Não	Autoriza exibir o consumidor em ranking
optIns	objeto	Não	Permissões de contato. Contém marketing (boolean)
region	objeto	Não	Endereço: street, postalcode, number, neighborhood, city, state

consumerReference é obrigatório só aqui

Nos check-ins por comanda e por RFID esse campo é opcional. No check-in de Wallet ele é obrigatório — sem ele a chamada falha com 400.

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

Resposta 201

Corpo vazio.

{}

Erros

Status	Código	Mensagem	Quando acontece
400	—	Missing customer reference (consumerReference)!	Faltou consumer.consumerReference
400	4001	This RFID card has an opened consumption.	Já existe sessão aberta para essa reference
422	4221	It was not possible to link the phone number with the document provided.	Telefone e documento pertencem a cadastros diferentes

Alterar consumidor

Troca ou completa os dados do consumidor de uma sessão aberta, sem encerrá-la.

PUT /places/{idPlace}/customers/{reference}

Corpo da requisição

Os mesmos campos de consumer em Abrir uma Wallet — name é obrigatório.

{
  "name": "Maria Silva",
  "consumerReference": "cliente-123",
  "email": "maria@example.com"
}

Resposta 200

Corpo vazio.

{}

Só os erros comuns.

Consultar transações

Retorna o extrato da Wallet.

GET /places/{idPlace}/customers/{reference}/transactions

Query string

Parâmetro	Tipo	Obrigatório	Descrição
startAt	string	Não	Início do período em ISO 8601
finishAt	string	Não	Fim do período em ISO 8601

startAt e finishAt só têm efeito quando enviados juntos.

Resposta 200

Lista de transações. Os campos estão descritos em Consultar transações da comanda — o formato é idêntico.

Campo	Tipo	Descrição
idTransaction	string	Identificador único. Use para não lançar duas vezes
total	number	Valor a lançar, em reais. Já vem calculado
type	string	D consumo, C recarga, P produto do parceiro

Só os erros comuns.

Registrar produto externo

Lança na Enjoy.it um item vendido no seu sistema. A transação sensibiliza o saldo.

POST /places/{idPlace}/customers/{reference}/transactions

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
createdAt	string	Sim	Data e hora da venda em ISO 8601. Participa da identificação da transação
product	string	Sim	Descrição do item
category	string	Sim	Categoria do item
quantity	number	Sim	Quantidade vendida
total	number	Não	Valor total da venda, em reais
sellingPrice	number	Não	Preço unitário praticado
price	number	Não	Preço de tabela
value	number	Não	Valor a debitar, quando diferente do total
sku	string	Não	Código do produto no seu catálogo
transactionReference	string	Não	Referência da venda no seu sistema
reference	string	Não	Referência auxiliar
reversed	boolean	Não	Marca a transação como estornada

{
  "createdAt": "2026-10-20T17:35:18.417Z",
  "product": "Coca-Cola lata",
  "category": "Bebidas",
  "transactionReference": "venda-987",
  "sellingPrice": 8.5,
  "quantity": 1,
  "total": 8.5
}

Resposta 201

A transação criada, sempre com type: "P".

Erros

Status	Código	Mensagem	Quando acontece
400	4002	This tab is not open.	A Wallet não tem sessão aberta
400	4003	Insufficient funds!	Saldo insuficiente para o valor lançado
400	4004	There is already a transaction for this customer with the createdAt provided.	Reenvio da mesma venda

Estornar transação

Cancela um lançamento já registrado, devolvendo o valor ao saldo.

DELETE /places/{idPlace}/customers/{reference}/transactions/{idTransaction}

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
idTransaction	string	Sim	O idTransaction devolvido em Consultar transações

Não possui corpo.

Resposta 200

Corpo vazio.

{}

Erros

Status	Código	Mensagem	Quando acontece
404	4040	Transaction not found!	O idTransaction não pertence ao extrato dessa Wallet

Registrar recarga

Credita saldo na Wallet. Chame somente depois de o pagamento ser aprovado.

POST /places/{idPlace}/customers/{reference}/recharges

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
value	number	Sim	Valor creditado, em reais
paymentMethod	string	Não	debit-card, credit-card, cash ou on-the-house (cortesia)

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

Resposta 201

Corpo vazio.

{}

Erros

Status	Código	Mensagem	Quando acontece
404	—	Missing value!	value ausente ou não numérico. Repare que o status é 404, não 400
400	4002	This tab is not open.	A Wallet não tem sessão aberta

Atualizar saldo

Sincroniza na Enjoy.it o saldo disponível para chope.

PUT /places/{idPlace}/customers/{reference}/balance

Query string

Parâmetro	Tipo	Obrigatório	Descrição
relative	boolean	Não	Com true, o valor enviado é somado ao saldo atual em vez de substituí-lo

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
balance	number	Condicional	Novo saldo em reais, ou a variação quando relative=true
glassPrice	number	Condicional	Valor do copo

Pelo menos um dos dois precisa ser enviado.

{
  "balance": 75.5
}

Resposta 200

Corpo vazio.

{}

Erros

Status	Mensagem	Quando acontece
400	Missing balance or glassPrice.	Corpo vazio ou sem nenhum dos dois campos

Encerrar Wallet

Encerra a sessão e bloqueia a credencial contra novas servidas.

POST /places/{idPlace}/customers/{reference}/checkout

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
products	lista de objetos	Sim	Itens do seu sistema ainda não enviados. Mande [] quando não houver nenhum

Cada item usa os mesmos campos de Registrar produto externo.

{ "products": [] }

Resposta 200

Corpo vazio.

{}

Erros

Status	Código	Mensagem	Quando acontece
400	4002	This tab is not open.	A Wallet já foi encerrada ou nunca foi aberta

Reiniciar Wallet

Desassocia o ciclo atual da credencial.

POST /places/{idPlace}/customers/{reference}/reset

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
keepBalance	boolean	Não	Com true, o saldo permanece disponível para o próximo ciclo

O corpo em si é obrigatório: envie ao menos {}.

{
  "keepBalance": false
}

Resposta 200

Corpo vazio.

{}

Só os erros comuns.