CUPOM PARA DESENVOLVEDORES

Integre cupons sem construir um motor promocional.

Envie o carrinho, o consumidor e o código. A API calcula o desconto e cuida das regras, budgets, limites, reservas, resgates e estornos.

Começar grátis Ver quickstart

Abrir referência da API

api.cupom.center

POST /v1/coupon/discount/single
Authorization: Bearer ••••••••

{
  "coupon_code": "BEMVINDO15",
  "context": {
    "user": { "id": "user-001" },
    "cart": [{
      "id": "CAMISETA-01",
      "quantity": 2,
      "unitary_price": 100
    }]
  }
}

200 OK

"totals": {
  "subtotal": 200,
  "product_discount": 30,
  "shipping_discount": 0,
  "discount": 30,
  "total": 170
}

UMA API, MENOS RESPONSABILIDADES

Seu produto envia o contexto. O Cupom resolve o restante.

A lógica promocional deixa de ficar espalhada entre checkout, aplicativo, ERP e serviços internos.

SEU BACKEND ENVIA

Código do cupom
Carrinho e preços
Consumidor e contexto
Frete e forma de pagamento
Pedido e referências externas

O CUPOM CONTROLA

Elegibilidade e vigência
Descontos e combinações
Limites e budget concorrente
Reservas e expiração
Resgates, pagamentos e estornos

Elegibilidade

Vigência, público, localização, pagamento, produtos, marcas, unidades e atributos.

Cálculo completo

Descontos por produto, quantidades, frete e múltiplos cupons no mesmo carrinho.

Limites e budgets

Controle por consumidor, distribuição total e orçamento mesmo sob concorrência.

Reservas

Cotações preservam o cálculo durante a jornada e expiram de forma controlada.

Idempotência

Repetições seguras evitam duplicidade em emissões, resgates, pagamentos e estornos.

Auditoria

Operações preservam contexto, revisão da regra, valores, comprovantes e reversões.

QUICKSTART

Do zero à primeira cotação.

01
Crie seu projeto
Abra uma conta e gere uma API key no ambiente de HML.
02
Configure o cupom
Defina desconto, produtos, público, limites, budget e vigência no painel.
03
Calcule o desconto
Envie o carrinho para a API e use os totais retornados no checkout.
04
Confirme o resgate
Quando a compra avançar, registre a operação de forma auditável.

HML e PRD usam https://api.cupom.center. A API key identifica organização, projeto e ambiente.

curl --request POST \
  'https://api.cupom.center/v1/coupon/discount/single' \
  --header 'Authorization: Bearer $CUPOM_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "cart_id": "cart-001",
  "coupon_code": "BEMVINDO15",
  "context": {
    "user": { "id": "user-001" },
    "cart": [{
      "id": "CAMISETA-01",
      "quantity": 2,
      "unitary_price": 100
    }],
    "shipping": { "amount": 25 }
  }
}'

const response = await fetch(
  'https://api.cupom.center/v1/coupon/discount/single',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.CUPOM_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
  "cart_id": "cart-001",
  "coupon_code": "BEMVINDO15",
  "context": {
    "user": { "id": "user-001" },
    "cart": [{
      "id": "CAMISETA-01",
      "quantity": 2,
      "unitary_price": 100
    }],
    "shipping": { "amount": 25 }
  }
}),
  },
)

if (!response.ok) throw new Error(`Cupom API: ${response.status}`)

const result = await response.json()
console.log(result.totals.total)

Resposta de exemplo200 OK

{
  "quote_id": "qte_01J...",
  "status": "reserved",
  "expires_at": "2026-11-04T15:30:00Z",
  "currency": "BRL",
  "totals": {
    "subtotal": 200,
    "shipping": 25,
    "product_discount": 30,
    "shipping_discount": 0,
    "discount": 30,
    "total": 195
  }
}

CICLO DA API

Da consulta ao estorno, cada etapa é explícita.

As chamadas autenticadas partem do seu backend. A API key nunca deve ser exposta no navegador.

01
QUERY/v1/coupon/eligibility
Consulte ofertas elegíveis sem alterar o estado da operação.
02
POST/v1/coupon/discount/single
Calcule e reserver o desconto para o carrinho.
03
POST/v1/coupon/redeem/single
Confirme o resgate quando a compra avançar.
04
POST/v1/coupon/operations/{id}/payments /v1/coupon/operations/{id}/refunds
Registre o pagamento ou reverta a operação quando necessário.

MCP OFICIAL PARA IA

Dê à sua IA o contexto certo para integrar.

O MCP conecta seu assistente de IA ao Cupom Center e ajuda a colocar a integração em funcionamento. Ele orienta a IA sobre os passos certos para encontrar cupons, calcular descontos, confirmar usos e desfazer operações, sem exigir que você explique todo o processo do zero.

Funciona no seu computador, junto da ferramenta de IA que você já usa.
Sua chave de acesso permanece configurada no seu próprio ambiente.
A IA consulta regras e cálculos diretamente no Cupom Center, reduzindo erros e retrabalho.

Ver no GitHub Pacote no npm

O servidor local não adiciona custo de hospedagem. As chamadas que ele faz à API REST seguem o consumo e os limites do plano da organização.

mcp.json

Instale pelo npm no seu cliente MCP

{
  "mcpServers": {
    "cupom-center": {
      "command": "npx",
      "args": ["-y", "@cupom_center/mcp@latest"],
      "env": {
        "CUPOM_API_KEY": "cpm_..."
      }
    }
  }
}

FERRAMENTAS

Comece com o cliente que você já usa.

Contrato OpenAPI e collections com autenticação e ambientes já configurados.

Referência OpenAPIExplore endpoints, payloads, respostas e erros.Schema OpenAPIUse o contrato JSON em ferramentas e geradores.InsomniaCollection com ambientes HML e PRD.PostmanCollection única. Defina token no environment selecionado; a API key determina o ambiente.

INTEGRAÇÕES

Conecte o Cupom à plataforma da sua operação.

Use a mesma camada de regras e controle nos canais em que sua empresa já vende.

Em breve

WooCommerce

Aplique as alocações do Cupom no carrinho e acompanhe resgates, pagamentos e estornos.

Em breve

VTEX

Integração planejada pelo Gift Card Provider Protocol para aplicar o desconto na jornada de compra.

Em breve

Shopify

Integração para lojas Plus e Enterprise com Discount Functions e acesso de rede.

PRONTO PARA INTEGRAR

Faça sua primeira chamada em HML.

Criar conta grátis Baixar collection Abrir documentação