QR Code

Use estes endpoints em totens de autoatendimento e jornadas sem cartão físico. Diferente da comanda e do RFID, o QR Code é criado pela própria API — não é uma credencial que já existe na loja.

Resumo

Método	Endpoint	Finalidade
POST	/places/{idPlace}/qrcodes/checkin	Criar um QR Code de consumo
POST	/places/{idPlace}/qrcodes/{qrCode}/recharges	Registrar uma recarga
POST	/places/{idPlace}/qrcodes/{qrCode}/methods/whatsapp	Enviar o QR Code por WhatsApp
DELETE	/places/{idPlace}/qrcodes?phone={phone}	Cancelar e substituir os QR Codes de um consumidor

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
qrCode	string	Sim	O código devolvido em Criar um QR Code

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.	O qrCode informado não corresponde a nenhuma credencial
423	4231	Place suspended!	O estabelecimento está suspenso

Não existe checkout de QR Code

A API não possui um endpoint de checkout equivalente ao de comanda, RFID e Wallet. Para impedir consumo na saída, use Cancelar e substituir e não entregue o novo código devolvido.

Criar um QR Code

Cadastra o consumidor, gera um novo código e abre a sessão. É o check-in do fluxo de totem.

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

Campos de consumer:

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome apresentado no totem e nos relatórios
cellphone	string	Não	Necessário para enviar o código por WhatsApp e para cancelar depois
consumerReference	string	Não	Código do consumidor no seu sistema
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,
  "consumer": {
    "name": "Maria Silva",
    "cellphone": "+5511999999999",
    "document": "12345678900"
  }
}

Resposta 201

Campo	Tipo	Descrição
qrcode	string	O código gerado. Guarde: é ele que identifica a credencial nas demais chamadas

{
  "qrcode": "ENJ0000123456ABCD"
}

aviso

A chave da resposta é qrcode, toda em minúsculas, enquanto o parâmetro de caminho dos outros endpoints é {qrCode}.

Guarde o código sem exibi-lo ainda: em operação pré-paga, entregue-o ao consumidor somente depois de registrar a recarga, senão ele vai à torneira e não consegue servir.

Erros

Status	Código	Mensagem	Quando acontece
422	4221	It was not possible to link the phone number with the document provided.	Telefone e documento pertencem a cadastros diferentes

Registrar uma recarga

Credita saldo no QR Code. Chame somente depois de o pagamento ser aprovado.

POST /places/{idPlace}/qrcodes/{qrCode}/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": 100,
  "paymentMethod": "credit-card"
}

Resposta 201

Corpo vazio. Só exiba, imprima ou envie o QR Code 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

Enviar por WhatsApp

Envia o QR Code e o saldo atual para o telefone cadastrado no check-in.

POST /places/{idPlace}/qrcodes/{qrCode}/methods/whatsapp

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
method	string	Sim	Único valor aceito hoje: whatsapp

Não possui corpo. O destino é o cellphone informado no check-in — se o consumidor não tiver telefone cadastrado, não há para onde enviar.

Resposta 200

Corpo vazio.

{}

Erros

Status	Mensagem	Quando acontece
400	Method not supported	method diferente de whatsapp
400	Missing qrCode	Caminho sem o código

Cancelar e substituir QR Codes do consumidor

Invalida todos os QR Codes ativos do consumidor no estabelecimento e devolve um novo código com os saldos consolidados.

DELETE /places/{idPlace}/qrcodes?phone={phone}

Query string

Parâmetro	Tipo	Obrigatório	Descrição
phone	string	Sim	Telefone do consumidor. Codifique o + como %2B

Não possui corpo.

Resposta 200

Campo	Tipo	Descrição
qrcode	string	Novo código, já ativo, que substitui todos os anteriores
balance	number	Soma dos saldos das credenciais canceladas, em reais
bonus	number	Soma dos créditos de cortesia das credenciais canceladas

{
  "qrcode": "ENJ0000987654WXYZ",
  "balance": 42.5,
  "bonus": 0
}

O que fazer com o novo código depende da sua intenção

Sua intenção	O que fazer
Substituir um código perdido	Entregue o novo código e remova os anteriores do totem ou do app
Encerrar o acesso na saída	Não exiba nem envie. O saldo consolidado segue a regra comercial combinada na homologação

Erros

Status	Código	Mensagem	Quando acontece
404	4042	User not found	Nenhum consumidor com esse telefone
404	4041	No QR codes found for this user	O consumidor existe, mas não tem QR Code ativo neste estabelecimento