Skip to main content

​
Visão geral

O sistema de Cupons de Desconto permite que você crie e gerencie cupons promocionais que podem ser aplicados durante o checkout. Os cupons suportam descontos percentuais ou valores fixos, com configurações flexíveis de validade e limites de uso.

​
Pré-requisitos

Antes de começar, você precisa:
  • Uma conta ativa na Upay
  • Sua API Key configurada (veja Autenticação)
  • Conhecimento básico de APIs REST

​
Funcionalidades

  • Tipos de desconto: Percentual (%) ou valor fixo (R$)
  • Validade configurável: Data de início e fim no formato ISO 8601
  • Limites de uso: Total de usos e por usuário (null = ilimitado)
  • Valor mínimo: Defina valor mínimo de compra em centavos
  • Valor máximo: Limite o desconto máximo em centavos (apenas para percentuais)
  • Produtos específicos: Aplique a todos os produtos ou apenas produtos selecionados
  • Validação pública: Endpoint público (sem autenticação) para validar cupons no checkout

​
Criando um cupom

​
Requisição Básica - Desconto Percentual

curl -X POST "https://upay-sistema-api.onrender.com/api/v1/coupons" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DESCONTO10",
    "discountType": "PERCENTAGE",
    "discountValue": 10,
    "description": "10% de desconto em qualquer compra"
  }'

​
Requisição - Desconto Fixo

curl -X POST "https://upay-sistema-api.onrender.com/api/v1/coupons" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "R$50OFF",
    "discountType": "FIXED",
    "discountValue": 5000,
    "description": "R$ 50,00 de desconto"
  }'

​
Resposta

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "DESCONTO10",
    "discountType": "PERCENTAGE",
    "discountValue": 10,
    "description": "10% de desconto em qualquer compra",
    "minPurchaseCents": null,
    "maxDiscountCents": null,
    "usageLimit": null,
    "perUserLimit": null,
    "validFrom": null,
    "validUntil": null,
    "productIds": [],
    "status": "ACTIVE",
    "usedCount": 0,
    "createdAt": "2025-12-30T00:00:00.000Z"
  }
}

​
Campos disponíveis

​
Campos obrigatórios

CampoTipoDescrição
codestringCódigo único do cupom. Máximo 50 caracteres. Apenas letras, números e hífen.
discountTypestringTipo de desconto. Valores: “PERCENTAGE” ou “FIXED”.
discountValuenumberValor do desconto. Para PERCENTAGE: valor percentual (ex: 10 = 10%). Para FIXED: valor em centavos (ex: 5000 = R$ 50,00). Mínimo: 1.

​
Campos opcionais

CampoTipoDescriçãoPadrão
descriptionstringDescrição do cupom. Máximo 500 caracteres.-
minPurchaseCentsnumberValor mínimo de compra em centavos. Mínimo: 0.null
maxDiscountCentsnumberValor máximo de desconto em centavos. Apenas para PERCENTAGE. Mínimo: 1.null
usageLimitnumberLimite total de usos do cupom. null = ilimitado. Mínimo: 1.null
perUserLimitnumberLimite de usos por usuário. null = ilimitado. Mínimo: 1.null
validFromstringData de início da validade. Formato ISO 8601. Exemplo: “2024-01-01T00:00:00Z”.null
validUntilstringData de fim da validade. Formato ISO 8601. Deve ser posterior a validFrom.null
productIdsarrayArray de IDs de produtos aplicáveis. Vazio ou null = todos os produtos.[]
statusstringStatus do cupom. Valores: “ACTIVE” ou “INACTIVE”.”ACTIVE”

​
📖 Exemplos Completos

​
Cupom Simples - 10% de Desconto

const response = await fetch('https://upay-sistema-api.onrender.com/api/v1/coupons', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: 'PROMO10',
    discountType: 'PERCENTAGE',
    discountValue: 10,
    description: '10% de desconto em qualquer compra'
  })
});

​
Cupom com Validade e Limites

const validFrom = new Date();
const validUntil = new Date();
validUntil.setDate(validUntil.getDate() + 30); // Válido por 30 dias

const response = await fetch('https://upay-sistema-api.onrender.com/api/v1/coupons', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: 'BLACKFRIDAY',
    discountType: 'PERCENTAGE',
    discountValue: 25,
    description: 'Black Friday - 25% de desconto',
    minPurchaseCents: 10000, // Mínimo R$ 100,00
    maxDiscountCents: 50000, // Máximo R$ 500,00 de desconto
    usageLimit: 1000, // Máximo 1000 usos totais
    perUserLimit: 1, // 1 uso por usuário
    validFrom: validFrom.toISOString(),
    validUntil: validUntil.toISOString()
  })
});

​
Cupom para Produtos Específicos

const response = await fetch('https://upay-sistema-api.onrender.com/api/v1/coupons', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: 'PRODUTOESPECIAL',
    discountType: 'FIXED',
    discountValue: 2000, // R$ 20,00 de desconto
    description: 'R$ 20,00 de desconto em produtos selecionados',
    productIds: [
      'produto-1-id',
      'produto-2-id'
    ]
  })
});

​
Validando um cupom

​
Endpoint Público (Checkout)

O endpoint de validação é público e não requer autenticação. Use-o no checkout para validar cupons: 
curl -X POST "https://upay-sistema-api.onrender.com/api/v1/coupons/validate" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DESCONTO10",
    "amountCents": 10000
  }'

​
Resposta - Cupom Válido

{
  "success": true,
  "valid": true,
  "data": {
    "code": "DESCONTO10",
    "discountType": "PERCENTAGE",
    "discountValue": 10,
    "discountAmount": 1000,
    "finalAmount": 9000,
    "description": "10% de desconto em qualquer compra"
  }
}

​
Resposta - Cupom Inválido

{
  "success": false,
  "valid": false,
  "message": "Cupom não encontrado ou inválido"
}

​
Exemplo em JavaScript (Checkout)

async function validateCoupon(code, amount) {
  const response = await fetch('https://upay-sistema-api.onrender.com/api/v1/coupons/validate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      code: code,
      amount: amount // Valor em centavos
    })
  });
  
  const data = await response.json();
  
  if (data.valid) {
    console.log(`Desconto: R$ ${(data.data.discountAmount / 100).toFixed(2)}`);
    console.log(`Valor final: R$ ${(data.data.finalAmount / 100).toFixed(2)}`);
    return data.data;
  } else {
    console.error(data.message);
    return null;
  }
}

​
🔍 Listando Cupons

​
Listar Todos os Cupons

curl -X GET "https://upay-sistema-api.onrender.com/api/v1/coupons?page=1&limit=20" \
  -H "Authorization: Bearer SUA_API_KEY"

​
Buscar Cupom Específico

curl -X GET "https://upay-sistema-api.onrender.com/api/v1/coupons/{id}" \
  -H "Authorization: Bearer SUA_API_KEY"

​
Atualizando um cupom

curl -X PATCH "https://upay-sistema-api.onrender.com/api/v1/coupons/{id}" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "INACTIVE",
    "usageLimit": 500
  }'
Você pode atualizar apenas os campos que desejar. Campos não enviados permanecerão inalterados.

​
🗑️ Deletando um Cupom

curl -X DELETE "https://upay-sistema-api.onrender.com/api/v1/coupons/{id}" \
  -H "Authorization: Bearer SUA_API_KEY"
A exclusão é permanente. Cupons já utilizados mantêm o histórico de uso.

​
Regras de validação

O sistema valida automaticamente:
  1. Código válido: O cupom existe e está ativo
  2. Validade: Data atual está entre validFrom e validUntil
  3. Limites de uso: Não excedeu usageLimit e perUserLimit
  4. Valor mínimo: Compra atinge minPurchaseCents
  5. Produtos aplicáveis: Produto está na lista productIds (se especificado)
  6. Desconto máximo: Para percentuais, respeita maxDiscountCents

​
🎯 Casos de Uso

​
Promoções Temporárias

Crie cupons com validade limitada para campanhas específicas.

​
Descontos por Volume

Configure valor mínimo de compra para incentivar compras maiores.

​
Cupons Exclusivos

Use limites de uso para criar cupons exclusivos ou limitados.

​
Produtos Específicos

Aplique descontos apenas a produtos selecionados do catálogo.

​
Primeira Compra

Configure perUserLimit: 1 para cupons de primeira compra.

​
Próximos passos

Referência da API

Veja todos os endpoints disponíveis

Links de Pagamento

Integre cupons no checkout