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",
"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
| Campo | Tipo | Descrição |
|---|
code | string | Código único do cupom. Máximo 50 caracteres. Apenas letras, números e hífen. |
discountType | string | Tipo de desconto. Valores: “PERCENTAGE” ou “FIXED”. |
discountValue | number | Valor do desconto. Para PERCENTAGE: valor percentual (ex: 10 = 10%). Para FIXED: valor em centavos (ex: 5000 = R$ 50,00). Mínimo: 1. |
Campos opcionais
| Campo | Tipo | Descrição | Padrão |
|---|
description | string | Descrição do cupom. Máximo 500 caracteres. | - |
minPurchaseAmount | number | Valor mínimo de compra em centavos. Mínimo: 0. | null |
maxDiscountAmount | number | Valor máximo de desconto em centavos. Apenas para PERCENTAGE. Mínimo: 1. | null |
maxUses | number | Limite total de usos do cupom. null = ilimitado. Mínimo: 1. | null |
maxUsesPerUser | number | Limite de usos por usuário. null = ilimitado. Mínimo: 1. | null |
validFrom | string | Data de início da validade. Formato ISO 8601. Exemplo: “2024-01-01T00:00:00Z”. | null |
validUntil | string | Data de fim da validade. Formato ISO 8601. Deve ser posterior a validFrom. | null |
productIds | array | Array de IDs de produtos aplicáveis. Vazio ou null = todos os produtos. | [] |
status | string | Status 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'
})
});
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',
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://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",
"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://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",
"maxUses": 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:
- Código válido: O cupom existe e está ativo
- Validade: Data atual está entre
validFrom e validUntil
- Limites de uso: Não excedeu
maxUses e maxUsesPerUser
- Valor mínimo: Compra atinge
minPurchaseAmount
- Produtos aplicáveis: Produto está na lista
productIds (se especificado)
- Desconto máximo: Para percentuais, respeita
maxDiscountAmount
🎯 Casos de Uso
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
