Consumidores

Estes endpoints são sobre a pessoa, não sobre a credencial que ela está usando. Valem para qualquer operação — comanda, RFID, QR Code ou Wallet — porque tratam do cadastro do consumidor no estabelecimento: localizar, verificar identidade e consolidar consumo.

Resumo

Método	Endpoint	Finalidade
`GET`	`/places/{idPlace}/customers`	Pesquisar consumidor
`GET`	`/places/{idPlace}/customers/{uid}/tabs`	Listar credenciais do consumidor
`POST`	`/places/{idPlace}/customers/{uid}/codes/methods/whatsapp`	Solicitar código de verificação
`POST`	`/places/{idPlace}/customers/{uid}/codes/{code}`	Verificar código
`GET`	`/places/{idPlace}/customers/ranking`	Ranking de consumidores
`GET`	`/places/{idPlace}/customers/birthday`	Aniversariantes do período

Aqui o caminho leva uid, não reference

Os endpoints de Wallet são identificados pela reference — o código do cliente no seu sistema. Nesta página, o valor esperado no caminho é o uid: o identificador do consumidor na Enjoy.it, devolvido em Pesquisar consumidor.

É a diferença entre as duas páginas: a Wallet trata da credencial que você abriu, e esta trata do cadastro da pessoa.

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
`uid`	string	Condicional	Identificador do consumidor na Enjoy.it

Erros comuns

Status	Código	Mensagem	Quando acontece
`403`	—	`Not authorized to interact with this place (idPlace)`	A chave não tem acesso a esse estabelecimento
`423`	`4231`	`Place suspended!`	O estabelecimento está suspenso

Pesquisar consumidor

Localiza consumidores por documento ou telefone. É por aqui que você obtém o uid exigido pelos demais endpoints desta página.

GET /places/{idPlace}/customers

Query string

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

Pelo menos um dos dois precisa ser enviado.

GET /places/P-PDV/customers?phone=%2B5511999999999

Resposta `200`

Lista de consumidores.

Campo	Tipo	Descrição
`uid`	string	Identificador do consumidor na Enjoy.it
`name`	string	Nome
`document`	string	Documento
`cellphone`	string	Telefone
`consumerReference`	string	Código do consumidor no seu sistema
`email`	string	E-mail
`gender`	string	`male`, `female` ou `other`
`birthdate`	string	Data de nascimento em ISO 8601
`region`	objeto	Endereço: `street`, `postalcode`, `number`, `neighborhood`, `city`, `state`

[
  {
    "uid": "5FS6DS0BDERIWG9QL6ojfuLedg23",
    "name": "Maria Silva",
    "cellphone": "+5511999999999",
    "consumerReference": "cliente-123"
  }
]

Erros

Status	Mensagem	Quando acontece
`400`	`Missing document or phone`	Nenhum dos dois parâmetros foi enviado

Listar credenciais do consumidor

Retorna as credenciais ativas do consumidor no estabelecimento.

GET /places/{idPlace}/customers/{uid}/tabs

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`uid`	string	Sim	`uid` do consumidor, obtido em Pesquisar consumidor. Não é a `reference`, apesar do nome do parâmetro na rota

Resposta `200`

Lista de credenciais no mesmo formato de Consultar Wallet. Traz apenas as que estão com status ativo no estabelecimento informado.

Só os erros comuns.

Solicitar código de verificação

Envia por WhatsApp um código para confirmar que a pessoa é a dona daquele cadastro. Use antes de reemitir uma credencial.

POST /places/{idPlace}/customers/{uid}/codes/methods/whatsapp

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`uid`	string	Sim	`uid` do consumidor, obtido em Pesquisar consumidor
`method`	string	Sim	Único valor aceito hoje: `whatsapp`

Não possui corpo. O número usado é o cellphone do cadastro do consumidor.

Resposta `200`

Campo	Tipo	Descrição
`cellphone`	string	Telefone para onde o código foi enviado
`method`	string	Canal usado no envio
`sentAt`	string	Data e hora do envio, em ISO 8601
`status`	string	Situação do código
`timeout`	number	Prazo de validade do código
`code`	string	O código gerado

Erros

Status	Código	Mensagem	Quando acontece
`400`	—	`Method not supported`	`method` diferente de `whatsapp`
`400`	—	`User has no cellphone`	O cadastro não tem telefone, e sem telefone não há como enviar
`404`	`4042`	`User not found`	O `uid` não corresponde a nenhum consumidor

Verificar código

Confere o código que o consumidor recebeu.

POST /places/{idPlace}/customers/{uid}/codes/{code}

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`uid`	string	Sim	`uid` do consumidor
`code`	string	Sim	Código informado pelo consumidor

Não possui corpo.

Resposta `200`

Mesmo formato de Solicitar código de verificação. Confira o campo status para saber se a validação passou.

Erros

Status	Código	Mensagem	Quando acontece
`400`	—	`Code is required`	Caminho sem o código
`400`	—	`User has no cellphone`	O cadastro não tem telefone
`404`	`4041`	`User not found`	O `uid` não corresponde a nenhum consumidor
`404`	`4042`	`Missing verify code`	Não há código pendente para esse telefone. Solicite um novo

Relatórios de consumidores

Os dois endpoints seguintes devolvem consumidores consolidados, não transações: cada item é uma pessoa, com o total que ela consumiu e os dados de contato. São feitos para ação de relacionamento — ranking na TV da loja, campanha de aniversário, régua de recompra —, não para conciliação financeira. Para valores, use Transações.

Modelo de consumidor consolidado

O mesmo formato nas duas respostas:

Campo	Tipo	Descrição
`uid`	string	Identificador do consumidor na Enjoy.it
`name`	string	Nome
`cellphone`	string	Telefone
`email`	string	E-mail
`document`	string	Documento
`gender`	string	`male`, `female` ou `other`
`birthdate`	string	Data de nascimento, em ISO 8601
`region`	objeto	Endereço: `street`, `postalcode`, `number`, `neighborhood`, `city`, `state`
`createdAt`	string	Data do cadastro do consumidor, em ISO 8601
`mlServed`	number	Volume total servido, em mililitros
`totalConsumed`	number	Valor total consumido, em reais
`topBrand`	string	Nome do produto que ele mais consumiu
`checkinsCount`	number	Quantas vezes ele abriu credencial
`lastConsumptionAt`	string	Data do último consumo, em ISO 8601
`marketing`	objeto	Autorização de contato. Ver abaixo

Campos de marketing:

Campo	Tipo	Descrição
`acceptMessages`	boolean	O consumidor aceita receber mensagens
`acceptEmails`	boolean	O consumidor aceita receber e-mails

Respeite o marketing antes de disparar campanha

acceptMessages e acceptEmails são a autorização que o próprio consumidor deu na Enjoy.it. Quando vêm false, aquele contato não pode ser usado para campanha. Filtre pelos dois campos antes de alimentar qualquer ferramenta de envio.

[
  {
    "uid": "5FS6DS0BDERIWG9QL6ojfuLedg23",
    "name": "Maria Silva",
    "cellphone": "+5511999999999",
    "email": "maria@example.com",
    "birthdate": "1990-05-20T00:00:00.000Z",
    "createdAt": "2025-11-14T18:02:11.000Z",
    "marketing": {
      "acceptMessages": true,
      "acceptEmails": false
    },
    "mlServed": 4820.5,
    "totalConsumed": 241.03,
    "topBrand": "IPA da Casa",
    "checkinsCount": 12,
    "lastConsumptionAt": "2026-08-02T19:43:29.416Z"
  }
]

Ranking de consumidores

Lista quem mais consumiu no período, ordenado por mlServed do maior para o menor.

GET /places/{idPlace}/customers/ranking

Query string

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

GET /places/P-PDV/customers/ranking?startAt=2026-08-01T00:00:00.000Z&finishAt=2026-08-31T23:59:59.999Z

Resposta `200`

Lista no modelo de consumidor consolidado. Entram apenas os consumidores que abriram credencial dentro do período, e os totais somam só o que foi consumido nessas visitas.

Erros

Status	Mensagem	Quando acontece
`400`	`Missing search params (startAt \| finishAt)`	Falta um dos dois, ou a data não é reconhecida

Aniversariantes do período

Lista os consumidores do estabelecimento cujo aniversário cai no período — o ano da data de nascimento é ignorado, só dia e mês contam. Vem ordenado por dia do mês.

GET /places/{idPlace}/customers/birthday

Query string

Parâmetro	Tipo	Obrigatório	Descrição
`startAt`	string	Sim	Início do período de aniversários, em ISO 8601
`finishAt`	string	Sim	Fim do período de aniversários, em ISO 8601

O uso comum é o mês corrente:

GET /places/P-PDV/customers/birthday?startAt=2026-08-01T00:00:00.000Z&finishAt=2026-08-31T23:59:59.999Z

Resposta `200`

Lista no modelo de consumidor consolidado. Consumidores sem birthdate no cadastro não aparecem.

O período filtra aniversários, não consumo

Diferente do ranking, aqui startAt e finishAt selecionam a data de aniversário. Os totais (mlServed, totalConsumed, checkinsCount) são do histórico completo do consumidor no estabelecimento, não do período informado.

Erros

Status	Mensagem	Quando acontece
`400`	`Missing search params (startAt \| finishAt)`	Falta um dos dois, ou a data não é reconhecida

Resumo​

Parâmetros e erros comuns​

Parâmetros de caminho​

Erros comuns​

Pesquisar consumidor​

Query string​

Resposta 200​

Erros​

Listar credenciais do consumidor​

Parâmetros de caminho​

Resposta 200​

Solicitar código de verificação​

Parâmetros de caminho​

Resposta 200​

Erros​

Verificar código​

Parâmetros de caminho​

Resposta 200​

Erros​

Relatórios de consumidores​

Modelo de consumidor consolidado​

Ranking de consumidores​

Query string​

Resposta 200​

Erros​

Aniversariantes do período​

Query string​

Resposta 200​

Erros​

Resumo

Parâmetros e erros comuns

Parâmetros de caminho

Erros comuns

Pesquisar consumidor

Query string

Resposta `200`

Erros

Listar credenciais do consumidor

Parâmetros de caminho

Resposta `200`

Solicitar código de verificação

Parâmetros de caminho

Resposta `200`

Erros

Verificar código

Parâmetros de caminho

Resposta `200`

Erros

Relatórios de consumidores

Modelo de consumidor consolidado

Ranking de consumidores

Query string

Resposta `200`

Erros

Aniversariantes do período

Query string

Resposta `200`

Erros