Cupons

CRUD de cupons de desconto via API Key. Mesmas regras do cadastro no painel; paginação por página.

GET /merchant/coupons → 200

Requer scope READ_COUPONS.

Query:

Campo	Tipo	Obrigatório	Regras / Default
q	string	não	busca em code e description
discountType	enum	não	PERCENT | FIXED
status	enum	não	ACTIVE | INACTIVE (status gravado, não o derivado — ver abaixo)
page	int	não	default 1
pageSize	int	não	máx 100, default 20

Resposta (200):

{
  "items": [
    {
      "id": "uuid",
      "code": "PROMO10",
      "description": "string | null",
      "discountType": "PERCENT",
      "discountValue": 10,
      "currency": "BRL",
      "minOrderAmountCents": null,
      "maxDiscountCents": null,
      "usageLimit": null,
      "maxRedemptionsPerCustomer": null,
      "status": "ACTIVE",
      "usageCount": 0,
      "revenueCents": 0,
      "discountGivenCents": 0,
      "validFrom": null,
      "validUntil": null,
      "createdAt": "2026-07-16T12:00:00.000Z",
      "updatedAt": "2026-07-16T12:00:00.000Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalCount": 1
}

• status na resposta é derivado, nesta ordem: INACTIVE (desativado manualmente) → SCHEDULED (antes de validFrom) → EXPIRED (depois de validUntil) → DEPLETED (usageCount atingiu usageLimit) → senão ACTIVE.
• usageCount, revenueCents e discountGivenCents somam apenas resgates confirmados.

POST /merchant/coupons → 201

Requer scope WRITE_COUPONS.

Body:

Campo	Tipo	Obrigatório	Regras / Default
code	string	sim	1–64; normalizado para maiúsculas; único por empresa (409 se já existir)
description	string	não	máx 500
discountType	enum PERCENT | FIXED	sim	—
discountValue	int	sim	PERCENT: inteiro 1–100. FIXED: inteiro ≥ 1 (centavos)
currency	string	não	3 chars; default "BRL"
minOrderAmountCents	int	não	≥ 0
maxDiscountCents	int	não	≥ 1 (teto de desconto)
usageLimit	int	não	≥ 1; limite total de usos
maxRedemptionsPerCustomer	int	não	≥ 1
validFrom / validUntil	string (datetime ISO)	não	se ambos informados, validUntil precisa ser depois de validFrom

Resposta (201): o cupom criado, no formato de item de listagem.

Exemplo — criar um cupom de 10% com teto e validade:

Criar cupom

curl -s -X POST https://goldpay-goldpay-api.f0czp0.easypanel.host/api/merchant/coupons \
  -H "X-Api-Key: <SECRET_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "PROMO10",
    "discountType": "PERCENT",
    "discountValue": 10,
    "maxDiscountCents": 5000,
    "validUntil": "2026-12-31T23:59:59.000Z"
  }'

GET /merchant/coupons/:id → 200

Requer scope READ_COUPONS. De outra empresa ou inexistente → 404.

PATCH /merchant/coupons/:id → 200

Requer scope WRITE_COUPONS. Todos os campos do body são opcionais (mesmas regras do POST, mais status: ACTIVE | INACTIVE), mas ao menos um precisa ser enviado (400 se vazio). code continua único por empresa (409 em conflito). Não encontrado → 404.

DELETE /merchant/coupons/:id → 204

Requer scope WRITE_COUPONS. Não encontrado → 404. Se o cupom já tiver resgates, a remoção não apaga o registro — apenas o desativa (status: INACTIVE), preservando o histórico de uso.

Remover cupom

curl -s -X DELETE https://goldpay-goldpay-api.f0czp0.easypanel.host/api/merchant/coupons/<COUPON_ID> \
  -H "X-Api-Key: <SECRET_KEY>" -o /dev/null -w '%{http_code}\n'
# 204 = removido/desativado

Dica

Não há idempotencyKey no POST: use um code estável para evitar duplicar cupons em re-tentativas e trate o 409 de conflito como “já existe”.