RFID

Use estes endpoints quando o parceiro lê diretamente o identificador RFID/NFC do cartão. Envie o código lido no parâmetro rfid.

Resumo

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

Singular e plural

A consulta individual e a abertura de torneira usam rfids. As demais operações usam rfid. Copie o caminho exatamente como documentado.

Parâmetros e erros comuns

Valem para todos os endpoints desta página.

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
rfid	string	Sim	Código do chip. A API completa com zeros à esquerda até 10 dígitos

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 credencial para esse chip no estabelecimento
423	4231	Place suspended!	O estabelecimento está suspenso

Consultar RFID

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

GET /places/{idPlace}/rfids/{rfid}

Resposta 200

Campo	Tipo	Descrição
rfid	string	Código do chip
idTab	string	Número da comanda vinculada, quando houver
uid	string	Identificador do consumidor na Enjoy.it
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. Vem false quando não definido
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 a operação cobra por ele
qrCode	string	QR Code vinculado, quando houver
customer	objeto	Dados do consumidor: uid, name, document, cellphone, consumerReference, email, gender, birthdate, region

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

Só os erros comuns.

Listar credenciais abertas

Retorna todas as credenciais com sessão aberta no estabelecimento.

GET /places/{idPlace}/rfid

Query string

Parâmetro	Tipo	Obrigatório	Descrição
sources	string	Não	Filtra por origem. Aceita vários valores separados por vírgula
lastTransactionAfter	string	Não	Data em ISO 8601. Retorna apenas credenciais com consumo posterior a ela

Resposta 200

Lista de objetos no mesmo formato de Consultar RFID.

Erros

Status	Mensagem	Quando acontece
400	Invalid lastTransactionAfter	A data enviada não é reconhecida como data válida

Abrir um RFID

Vincula o consumidor à credencial e libera o consumo. É o check-in.

POST /places/{idPlace}/rfid/{rfid}/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 a operação cobra por ele
reopenTab	string	Não	Reabre uma sessão anterior em vez de criar uma nova
idTab	string	Não	Número de comanda a associar a este chip

Campos de consumer:

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome apresentado no totem e nos relatórios
consumerReference	string	Não	Recomendado. O código do consumidor no seu sistema
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

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

Resposta 201

Corpo vazio. Só entregue o cartão ao consumidor depois de receber este 201.

{}

Erros

Status	Código	Mensagem	Quando acontece
400	4001	This RFID card has an opened consumption.	O cartão já tem sessão aberta. Faça o checkout antes
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 já aberta, sem encerrá-la.

PUT /places/{idPlace}/rfid/{rfid}/customers

Corpo da requisição

Os mesmos campos de consumer em Abrir um RFID — 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 credencial: consumos de chope, recargas e produtos lançados pelo parceiro.

GET /places/{idPlace}/rfid/{rfid}/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, ordenada por createdAt. Os campos estão descritos em Consultar transações da comanda — o formato é idêntico.

Os três que mais importam:

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 PDV. A transação sensibiliza o saldo do consumidor.

POST /places/{idPlace}/rfid/{rfid}/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". Os campos mlServed e idTap não se aplicam e vêm ausentes.

Erros

Status	Código	Mensagem	Quando acontece
400	4002	This tab is not open.	A credencial 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. Normalmente é a proteção contra duplicidade funcionando

Estornar transação

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

DELETE /places/{idPlace}/rfid/{rfid}/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 credencial

Registrar recarga

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

POST /places/{idPlace}/rfid/{rfid}/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. Só apresente o novo saldo ao consumidor depois deste 201.

{}

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 credencial não tem sessão aberta

Atualizar saldo

Sincroniza na Enjoy.it o saldo que o consumidor ainda tem disponível para chope.

PUT /places/{idPlace}/rfid/{rfid}/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

Trocar RFID

Transfere a sessão para outro cartão, preservando consumos e saldo. Use quando o consumidor perder ou danificar o cartão.

PUT /places/{idPlace}/rfid

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
currentRfid	string	Sim	Chip em uso. Completado com zeros à esquerda até 10 dígitos
newRfid	string	Sim	Chip que passará a valer. Precisa estar livre

{
  "currentRfid": "4623227593",
  "newRfid": "4623227821"
}

Resposta 200

Corpo vazio.

{}

Erros

Status	Mensagem	Quando acontece
400	Missing currentRfid or newRfid.	Faltou um dos dois campos
400	The current tab is not in use.	A credencial de origem não tem sessão aberta
400	The new tab is already in use.	A credencial de destino já está com outro consumidor

Encerrar RFID

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

POST /places/{idPlace}/rfid/{rfid}/checkout

Corpo da requisição

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

Cada item usa os mesmos campos de Registrar produto externo.

{ "products": [] }

aviso

Não repita aqui produtos já enviados por Registrar produto externo — seriam lançados duas vezes.

Resposta 200

Corpo vazio. Só libere o consumidor e reutilize o cartão depois deste 200.

{}

Erros

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

Reiniciar RFID

Desassocia o ciclo atual da credencial, deixando o cartão pronto para outro uso.

POST /places/{idPlace}/rfid/{rfid}/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.