Cupons

Crie, liste, consulte, atualize e remova cupons de desconto.

Cupons representam descontos configurados pelo merchant. Eles podem conceder um percentual ou um valor fixo, possuir período de validade e limitar a quantidade de utilizações.

Criar cupom

Requer uma API key FULL_ACCESS.

Consultar cupons

Aceita API keys READ_ONLY e FULL_ACCESS.

Alterar cupons

Atualização e remoção exigem uma API key FULL_ACCESS.

Tipos de desconto

PERCENTAGE

value representa um percentual inteiro entre 1 e 100. Para conceder 15% de desconto, envie 15.

FIXED_AMOUNT

value representa o desconto em centavos. Para conceder R$ 20,00 de desconto, envie 2000.

Criar um cupom

Desconto percentual

curl --request POST 'https://api-sandbox.fortalpay.tech/v1/coupons' \
  --header 'Authorization: ApiKey <full_access_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "BEMVINDO10",
    "type": "PERCENTAGE",
    "value": 10,
    "max_uses": 100,
    "starts_at": "2026-08-10",
    "expires_at": "2026-08-31"
  }'

Desconto fixo ilimitado

curl --request POST 'https://api-sandbox.fortalpay.tech/v1/coupons' \
  --header 'Authorization: ApiKey <full_access_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "code": "MENOS2000",
    "type": "FIXED_AMOUNT",
    "value": 2000,
    "max_uses": -1
  }'

Campos da criação

Campo	Obrigatório	Regra
code	Sim	Código com até 50 caracteres. É normalizado em letras maiúsculas e deve ser único no merchant.
type	Sim	PERCENTAGE ou FIXED_AMOUNT.
value	Sim	Percentual inteiro de 1 a 100 ou valor fixo em centavos, conforme o tipo.
max_uses	Não	Limite positivo. Use null, omita o campo ou envie -1 para uso ilimitado.
starts_at	Não	Início da validade em yyyy-MM-dd (início do dia) ou yyyy-MM-dd'T'HH:mm:ss.
expires_at	Não	Fim da validade em yyyy-MM-dd (fim do dia) ou yyyy-MM-dd'T'HH:mm:ss; deve ser posterior a starts_at.

A criação retorna HTTP 201, inicia used_count em 0 e define o status como ACTIVE.

Listar cupons

curl --request GET 'https://api-sandbox.fortalpay.tech/v1/coupons?page=0&size=20' \
  --header 'Authorization: ApiKey <api_key>'

A listagem retorna somente cupons do merchant autenticado que não foram removidos logicamente, ordenados pela data de criação em ordem decrescente.

Consultar pelo identificador

curl --request GET 'https://api-sandbox.fortalpay.tech/v1/coupons/<coupon_id>' \
  --header 'Authorization: ApiKey <api_key>'

Um identificador inexistente, removido ou pertencente a outro merchant retorna 404.

Atualizar um cupom

PUT /coupons/{id} realiza uma atualização parcial. Envie somente os campos que precisam mudar.

curl --request PUT 'https://api-sandbox.fortalpay.tech/v1/coupons/<coupon_id>' \
  --header 'Authorization: ApiKey <full_access_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "value": 15,
    "max_uses": 200,
    "expires_at": "2026-09-30",
    "status": "ACTIVE"
  }'

Todos os campos da criação podem ser atualizados, além de status, que aceita ACTIVE ou INACTIVE. As regras do tipo, valor, período e limite de usos são revalidadas após a alteração.

O corpo deve conter ao menos um valor não nulo. Atualmente, enviar null em max_uses, starts_at ou expires_at não limpa o valor existente; o campo é ignorado. Para tornar o uso ilimitado, envie max_uses: -1.

Quando o cupom pode ser usado

Um cupom somente está disponível quando todas estas condições são atendidas:

• O status é ACTIVE.
• A data atual não é anterior a starts_at, quando informada.
• A data atual não é posterior a expires_at, quando informada.
• used_count ainda é menor que max_uses, salvo quando o uso é ilimitado.

Remover um cupom

curl --request DELETE 'https://api-sandbox.fortalpay.tech/v1/coupons/<coupon_id>' \
  --header 'Authorization: ApiKey <full_access_api_key>'

A remoção é lógica e retorna HTTP 204 sem corpo. O cupom deixa de aparecer na listagem, não pode mais ser consultado e não fica disponível para novos usos. Registros históricos permanecem preservados.

Campos retornados

Campo	Tipo	Descrição
id	UUID	Identificador público do cupom.
code	string	Código normalizado em letras maiúsculas.
type	enum	PERCENTAGE ou FIXED_AMOUNT.
value	number	Percentual inteiro ou valor fixo em reais com duas casas decimais.
max_uses	integer | null	Limite configurado; null ou -1 representa uso ilimitado.
used_count	integer	Quantidade de usos registrada.
starts_at	date-time | null	Início opcional da validade.
expires_at	date-time | null	Fim opcional da validade.
status	enum	ACTIVE ou INACTIVE.
created_at	date-time	Data de criação.
updated_at	date-time	Data da última atualização.