Cupons de Desconto - Alpa Gateway API

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 Alpa
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://alpa-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://alpa-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

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.	-
`minPurchaseCents`	number	Valor mínimo de compra em centavos. Mínimo: 0.	null
`maxDiscountCents`	number	Valor máximo de desconto em centavos. Apenas para PERCENTAGE. Mínimo: 1.	null
`usageLimit`	number	Limite total de usos do cupom. null = ilimitado. Mínimo: 1.	null
`perUserLimit`	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://alpa-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://alpa-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://alpa-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://alpa-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://alpa-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://alpa-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://alpa-sistema-api.onrender.com/api/v1/coupons/{id}" \
  -H "Authorization: Bearer SUA_API_KEY"

Atualizando um cupom

curl -X PATCH "https://alpa-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://alpa-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 usageLimit e perUserLimit
Valor mínimo: Compra atinge minPurchaseCents
Produtos aplicáveis: Produto está na lista productIds (se especificado)
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

​Visão geral

​Pré-requisitos

​Funcionalidades

​Criando um cupom

​Requisição Básica - Desconto Percentual

​Requisição - Desconto Fixo

​Resposta

​Campos disponíveis

​Campos obrigatórios

​Campos opcionais

​📖 Exemplos Completos

​Cupom Simples - 10% de Desconto

​Cupom com Validade e Limites

​Cupom para Produtos Específicos

​Validando um cupom

​Endpoint Público (Checkout)

​Resposta - Cupom Válido

​Resposta - Cupom Inválido

​Exemplo em JavaScript (Checkout)

​🔍 Listando Cupons

​Listar Todos os Cupons

​Buscar Cupom Específico

​Atualizando um cupom

​🗑️ Deletando um Cupom

​Regras de validação

​🎯 Casos de Uso

​Promoções Temporárias

​Descontos por Volume

​Cupons Exclusivos

​Produtos Específicos

​Primeira Compra

​Próximos passos

Referência da API

Links de Pagamento

Visão geral

Pré-requisitos

Funcionalidades

Criando um cupom

Requisição Básica - Desconto Percentual

Requisição - Desconto Fixo

Resposta

Campos disponíveis

Campos obrigatórios

Campos opcionais

📖 Exemplos Completos

Cupom Simples - 10% de Desconto

Cupom com Validade e Limites

Cupom para Produtos Específicos

Validando um cupom

Endpoint Público (Checkout)

Resposta - Cupom Válido

Resposta - Cupom Inválido

Exemplo em JavaScript (Checkout)

🔍 Listando Cupons

Listar Todos os Cupons

Buscar Cupom Específico

Atualizando um cupom

🗑️ Deletando um Cupom

Regras de validação

🎯 Casos de Uso

Promoções Temporárias

Descontos por Volume

Cupons Exclusivos

Produtos Específicos

Primeira Compra

Próximos passos