Cupons

Cupom é um código promocional do estabelecimento: o consumidor informa o código na hora da recarga e recebe bônus, desconto ou crédito. Estes endpoints administram o cadastro dos cupons — criar, alterar, listar e acompanhar quem resgatou.

Resumo

Método	Endpoint	Finalidade
GET	/places/{idPlace}/vouchers	Listar cupons
GET	/places/{idPlace}/vouchers/{idVoucher}	Consultar um cupom
POST	/places/{idPlace}/vouchers	Criar um cupom
PUT	/places/{idPlace}/vouchers/{idVoucher}	Alterar um cupom

Na API o cupom se chama voucher

O caminho é /vouchers e o campo do código é idVoucher — é o nome que a API usa desde a primeira versão. Cupom e voucher são a mesma coisa aqui.

Aqui você cadastra; o resgate acontece na recarga

Não existe endpoint de resgate nesta API. O código é aplicado quando o consumidor recarrega pelo aplicativo da Enjoy.it ou pelo Enjoy PDV, e é nesse momento que todas as regras do cupom são verificadas. O que você faz por aqui é manter o cadastro e consultar os resgates, na lista uses.

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
idVoucher	string	Condicional	O próprio código do cupom. Convertido para maiúsculas pela API

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	—	ItemNotFoundException	O idVoucher informado não existe

O código é global na plataforma

O idVoucher é o código digitado pelo consumidor, e ele é único em toda a Enjoy.it — não apenas dentro do seu estabelecimento. Se outro estabelecimento já usou VERAO2026, a sua criação responde 409.

Use um prefixo seu para não colidir:

Evite	Prefira
PROMO10	PDVX-PROMO10

Aceita letras, números, _, . e -. Como a API converte para maiúsculas, verao2026 e VERAO2026 são o mesmo cupom: mande sempre em maiúsculas para o log ficar igual ao cadastro.

Tipos de cupom

O campo type define o que o consumidor ganha, e muda o significado de value:

type	O que faz	Como value é lido
bonus-recharge	Bônus sobre a recarga	Percentual. value: 10 em uma recarga de R$ 100 gera R$ 10 de bônus
discount-recharge	Desconto na recarga	Percentual, mesma conta do bônus
credit	Crédito de valor fixo	Reais. value: 15 credita R$ 15

Nos dois tipos percentuais, maxValue limita o bônus em reais: value: 20 com maxValue: 30 em uma recarga de R$ 500 credita R$ 30, não R$ 100.

O bônus entra como saldo de bônus da credencial, separado do saldo recarregado.

Listar cupons

Retorna os cupons do estabelecimento. Cupons com status archived não aparecem.

GET /places/{idPlace}/vouchers

Resposta 200

Lista de cupons.

Campo	Tipo	Descrição
idVoucher	string	O código do cupom
idPlace	string	Estabelecimento dono do cupom
name	string	Nome interno da promoção
type	string	bonus-recharge, discount-recharge ou credit
value	number	Percentual ou valor, conforme o tipo
maxValue	number	Teto do bônus em reais, nos tipos percentuais
status	string	enable ou disabled
quantity	number	Total de resgates permitidos
usesCount	number	Quantos resgates já aconteceram
uses	lista	Um item por resgate. Ver tabela abaixo
singleUse	boolean	Se o cupom morre no primeiro resgate
multipleRedeem	boolean	Se o mesmo consumidor pode resgatar mais de uma vez
newUsers	boolean	Se é restrito a quem nunca recarregou
redeemInApp	boolean	Se pode ser resgatado no aplicativo do consumidor
redeemInPdv	boolean	Se pode ser resgatado no PDV
automatic	boolean	Se é oferecido automaticamente nas telas da Enjoy.it
condition	objeto	Condição sobre o valor da recarga. Ver Condição de recarga
idsTap	lista	Torneiras em que o cupom vale. Vazio significa todas
startAt	number	Início da validade, em milissegundos
endAt	number	Fim da validade, em milissegundos
allowed	lista	Consumidores autorizados. Vazio significa todos
disallowed	lista	Consumidores bloqueados

Campos de cada item de uses, allowed e disallowed:

Campo	Tipo	Descrição
uid	string	Identificador do consumidor na Enjoy.it
document	string	Documento do consumidor
phone	string	Telefone do consumidor
createdAt	string	Em uses, data e hora do resgate, em ISO 8601

[
  {
    "idVoucher": "PDVX-VERAO2026",
    "idPlace": "P-PDV",
    "name": "Verão 2026 — 10% de bônus",
    "type": "bonus-recharge",
    "value": 10,
    "maxValue": 30,
    "status": "enable",
    "quantity": 500,
    "usesCount": 2,
    "singleUse": false,
    "multipleRedeem": false,
    "newUsers": false,
    "redeemInApp": true,
    "redeemInPdv": true,
    "automatic": false,
    "condition": {
      "active": true,
      "type": "GreaterThanOrEqualTo",
      "value": 50
    },
    "startAt": 1767225600000,
    "endAt": 1772409599000,
    "uses": [
      {
        "uid": "5FS6DS0BDERIWG9QL6ojfuLedg23",
        "document": "12345678900",
        "phone": "+5511999999999",
        "createdAt": "2026-08-02T19:43:29.416Z"
      }
    ]
  }
]

Só os erros comuns.

Consultar um cupom

GET /places/{idPlace}/vouchers/{idVoucher}

Resposta 200

Um objeto no mesmo formato de Listar cupons. Diferente da listagem, aqui um cupom archived também é retornado.

Erros

Além dos comuns:

Status	Código	Mensagem	Quando acontece
403	—	This voucher is from other place (idPlace)	O código existe, mas pertence a outro estabelecimento

Criar um cupom

POST /places/{idPlace}/vouchers

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
idVoucher	string	Sim	O código que o consumidor vai digitar. Ver O código é global
name	string	Sim	Nome interno da promoção
type	string	Sim	bonus-recharge, discount-recharge ou credit
value	number	Sim	Percentual ou valor, conforme o tipo. Mínimo 0
singleUse	boolean	Sim	true encerra o cupom no primeiro resgate
newUsers	boolean	Sim	true restringe a quem nunca fez recarga na loja
redeemInApp	boolean	Sim	Libera o resgate no aplicativo do consumidor
redeemInPdv	boolean	Sim	Libera o resgate no PDV
quantity	number	Condicional	Total de resgates permitidos. Obrigatório quando singleUse é false; mínimo 1
maxValue	number	Não	Teto do bônus em reais, nos tipos percentuais
multipleRedeem	boolean	Não	true permite que o mesmo consumidor resgate várias vezes. Padrão false
automatic	boolean	Não	Marca o cupom para ser oferecido automaticamente nas telas da Enjoy.it. Não altera as regras de resgate
condition	objeto	Não	Exige um valor mínimo ou máximo de recarga. Ver Condição de recarga
idsTap	lista	Não	Restringe o cupom a torneiras específicas
startAt	number	Não	Início da validade, em milissegundos
endAt	number	Não	Fim da validade, em milissegundos
allowed	lista	Não	Só estes consumidores podem resgatar
disallowed	lista	Não	Estes consumidores não podem resgatar

idPlace vem do caminho: se você mandar esse campo no corpo, ele é ignorado.

startAt e endAt não são ISO 8601

Estes dois campos são a exceção à regra de datas da API: eles são números em milissegundos desde 1970 (UTC), o que em JavaScript é new Date('2026-01-01T00:00:00Z').getTime(). Mandar "2026-01-01" aqui não gera erro de validação — o cupom simplesmente nunca fica válido.

Em allowed e disallowed, cada item identifica o consumidor por uid, document ou phone; qualquer um dos três serve, e basta um deles casar.

{
  "idVoucher": "PDVX-VERAO2026",
  "name": "Verão 2026 — 10% de bônus",
  "type": "bonus-recharge",
  "value": 10,
  "maxValue": 30,
  "quantity": 500,
  "singleUse": false,
  "multipleRedeem": false,
  "newUsers": false,
  "redeemInApp": true,
  "redeemInPdv": true,
  "condition": {
    "active": true,
    "type": "GreaterThanOrEqualTo",
    "value": 50
  },
  "startAt": 1767225600000,
  "endAt": 1772409599000
}

Resposta 201

Corpo vazio. O cupom já nasce com status enable e usesCount 0.

{}

Erros

Além dos comuns:

Status	Código	Mensagem	Quando acontece
400	4001	Invalid idVucher (only letters and numbers)!	O código tem caractere fora de letras, números, _, . e -
409	4091	Voucher already exists!	Já existe esse código na plataforma. Escolha outro

Alterar um cupom

PUT /places/{idPlace}/vouchers/{idVoucher}

Corpo da requisição

Os mesmos campos de Criar um cupom, mais:

Campo	Tipo	Obrigatório	Descrição
status	string	Não	enable, disabled ou archived. Quando ausente, o status atual é mantido

A alteração substitui o cadastro inteiro

Não é uma alteração parcial. O cupom é regravado com o que você mandou, então todo campo opcional omitido é apagado — mandar só {"value": 15} zera condition, maxValue, idsTap, startAt, endAt, allowed e disallowed, e derruba os obrigatórios na validação.

Leia o cupom com Consultar um cupom, altere o que precisa e mande o objeto completo de volta.

uses e usesCount são preservados — o histórico de resgates não se perde.

Para encerrar uma promoção, use status: disabled bloqueia novos resgates e mantém o cupom na listagem; archived some da listagem.

Resposta 200

Corpo vazio.

{}

Erros

Além dos comuns:

Status	Código	Mensagem	Quando acontece
400	4001	Invalid idVucher (only letters and numbers)!	O código tem caractere inválido
403	—	This voucher is from other place (idPlace)	O cupom pertence a outro estabelecimento

Regras de resgate

Estas regras são avaliadas no momento do resgate, pelo aplicativo ou pelo PDV — não nos endpoints desta página. Vale conhecê-las porque são elas que definem se a promoção que você cadastrou vai funcionar como você espera:

Regra	Efeito quando não é atendida
Credencial pré-paga	Cupom só é resgatado em credencial prepaid
status enable	Cupom desabilitado não é aceito
quantity	Esgotado o total de resgates, ninguém mais resgata
singleUse	Depois do primeiro resgate, o cupom fecha
multipleRedeem	Com false, o consumidor que já resgatou não resgata de novo
condition	A recarga fora da faixa não recebe o benefício
startAt / endAt	Fora da janela, o cupom não vale
idsTap	Em outra torneira, o cupom não vale
allowed / disallowed	Fora da lista de autorizados, ou dentro da de bloqueados, não resgata
newUsers	Quem já fez recarga no estabelecimento não resgata
redeemInApp / redeemInPdv	O canal desabilitado não aceita o código
Mesma rede	O cupom vale na loja que o criou e nas lojas da mesma empresa

Condição de recarga

condition amarra o cupom a um valor de recarga:

Campo	Tipo	Descrição
active	boolean	true liga a condição
type	string	GreaterThanOrEqualTo (recarga mínima) ou LessThanOrEqualTo (recarga máxima)
value	number	O valor da comparação, em reais

{
  "active": true,
  "type": "GreaterThanOrEqualTo",
  "value": 50
}

Com o exemplo acima, uma recarga de R$ 30 não recebe o bônus; uma de R$ 50 recebe.