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.

​
✨ Funcionalidades

  • ✅ Tipos de Desconto: Percentual ou valor fixo
  • ✅ Validade Configurável: Data de início e fim
  • ✅ Limites de Uso: Total e por usuário
  • ✅ Valor Mínimo: Defina valor mínimo de compra
  • ✅ Valor Máximo: Limite o desconto máximo (para percentuais)
  • ✅ Produtos Específicos: Aplique a todos ou produtos selecionados
  • ✅ Validação Pública: Endpoint público para validar cupons no checkout

​
🚀 Criando um Cupom

​
Requisição Básica - Desconto Percentual

curl -X POST "https://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://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",
    "minPurchaseAmount": null,
    "maxDiscountAmount": null,
    "maxUses": null,
    "maxUsesPerUser": null,
    "validFrom": null,
    "validUntil": null,
    "productIds": [],
    "status": "ACTIVE",
    "usedCount": 0,
    "createdAt": "2025-12-30T00:00:00.000Z"
  }
}

​
📋 Campos Disponíveis

​
Campos Obrigatórios

  • code (string): Código do cupom (único, máx. 50 caracteres)
  • discountType (enum): “PERCENTAGE” ou “FIXED”
  • discountValue (number):
    • Para PERCENTAGE: valor percentual (ex: 10 = 10%)
    • Para FIXED: valor em centavos (ex: 5000 = R$ 50,00)

​
Campos Opcionais

  • description (string): Descrição do cupom
  • minPurchaseAmount (number): Valor mínimo de compra em centavos
  • maxDiscountAmount (number): Valor máximo de desconto em centavos (apenas para PERCENTAGE)
  • maxUses (number): Limite total de usos (null = ilimitado)
  • maxUsesPerUser (number): Limite de usos por usuário (null = ilimitado)
  • validFrom (string): Data de início (ISO 8601)
  • validUntil (string): Data de fim (ISO 8601)
  • productIds (array): IDs dos produtos aplicáveis (vazio = todos)
  • status (enum): “ACTIVE” ou “INACTIVE” (padrão: “ACTIVE”)

​
📖 Exemplos Completos

​
Cupom Simples - 10% de Desconto

const response = await fetch('https://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://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',
    minPurchaseAmount: 10000, // Mínimo R$ 100,00
    maxDiscountAmount: 50000, // Máximo R$ 500,00 de desconto
    maxUses: 1000, // Máximo 1000 usos totais
    maxUsesPerUser: 1, // 1 uso por usuário
    validFrom: validFrom.toISOString(),
    validUntil: validUntil.toISOString()
  })
});

​
Cupom para Produtos Específicos

const response = await fetch('https://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://https://upay-sistema-api.onrender.com//api/v1/coupons/validate" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "DESCONTO10",
    "amount": 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://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://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://https://upay-sistema-api.onrender.com//api/v1/coupons/{id}" \
  -H "Authorization: Bearer SUA_API_KEY"

​
✏️ Atualizando um Cupom

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

​
🗑️ Deletando um Cupom

curl -X DELETE "https://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 maxUses e maxUsesPerUser
  4. ✅ Valor mínimo: Compra atinge minPurchaseAmount
  5. ✅ Produtos aplicáveis: Produto está na lista productIds (se especificado)
  6. ✅ Desconto máximo: Para percentuais, respeita maxDiscountAmount

​
🎯 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 maxUsesPerUser: 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