API legada/Referência completa/Promoções, cupons e banners

Rotas de cupons

Valida um cupom contra um carrinho e consulta o uso de um cupom.

Um cupom é o código que ativa uma promoção. Estas duas rotas respondem às perguntas práticas de quem integra um carrinho ou um painel: "este código vale para este carrinho, e quanto desconta?" e "quantas vezes este código foi usado?". A comparação do código não diferencia maiúscula de minúscula, e o código volta em minúscula nas respostas.

POST/api/v1.0/coupons/{code}/validateAutenticada

Validar um cupom contra um carrinho

Calcula se o cupom se aplica ao carrinho e qual é o desconto, sem consumir o cupom. Um cupom inexistente, vencido ou que não atende às condições não é erro HTTP: a resposta é 200 com "valid": false e o motivo em message. Qualquer usuário autenticado pode chamar.

Parâmetros de caminho

codestringobrigatório

Código do cupom.

Corpo da requisição

cart_totalstringobrigatório

Total do carrinho em decimal com ponto, em reais ("150.00").

user_idstring

Id do cliente, quando o cupom tem regra por cliente.

itemsarray

Itens do carrinho, usados por cupons com condição de produto, categoria ou seller.

product_idstring

Id do produto.

category_idstring

Id da categoria principal.

category_idsarray

Todas as categorias do produto. Quando vem, tem preferência sobre category_id.

vendor_idstring

Id do seller.

quantityinteger

Quantidade.

pricestring

Preço unitário em decimal com ponto ("89.90").

GET/api/v1.0/coupons/{code}/usageAdmin

Consultar o uso de um cupom

Devolve o resumo de uso de um cupom ativo: quantos usos, quantos clientes diferentes, quanto desconto foi dado e quando foi usado pela primeira e pela última vez.

Parâmetros de caminho

codestringobrigatório

Código do cupom.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/coupons/BEMVINDO10/validate" \
  -H "Content-Type: application/json" \
  -d '{"cart_total":"150.00","items":[{"product_id":"d8a6c5e7-8e44-4055-a0e2-49014f5d17f6","quantity":1,"price":"150.00"}]}'

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/coupons/BEMVINDO10/usage"

Resposta

200Cupom que não vale

json

{
  "applies_to": "cart",
  "code": "nope",
  "discount_amount": "0.00",
  "discount_type": "",
  "message": "cupom não encontrado ou inativo",
  "promotion_id": "",
  "valid": false
}

200Uso do cupom

json

{
  "code": "bemvindo10",
  "promotion_id": "2b6f1c5e-8d3a-4f6e-9a0b-6c1d7e2f3a44",
  "promotion_name": "10% no primeiro pedido",
  "max_uses": 100,
  "total_uses": 12,
  "remaining": 88,
  "unique_users": 12,
  "total_discount_given": "184.50",
  "first_used_at": "2026-10-02T13:05:11Z",
  "last_used_at": "2026-10-11T18:42:07Z"
}

Campos da resposta

codestring

Código do cupom, em minúscula.

validboolean

true quando o cupom se aplica ao carrinho.

discount_amountstring

Desconto em decimal ("15.00"). "0.00" quando não vale.

discount_typestring

Tipo do desconto da promoção; vazio quando não vale.

applies_tostring

Onde o desconto incide; hoje cart.

promotion_idstring

Id da promoção do cupom; vazio quando não vale.

promotion_namestring

Nome da promoção.

messagestring

Motivo, em português, quando o cupom não vale. A mensagem vem como o servidor a devolve.

max_usesinteger

Limite de usos; 0 sem limite.

total_usesinteger

Usos até agora.

remaininginteger

Usos que faltam; -1 quando não há limite.

unique_usersinteger

Clientes diferentes que usaram.

total_discount_givenstring

Soma dos descontos dados, em decimal.

first_used_atstring

Primeiro uso, em RFC 3339 (UTC). Vazio se nunca foi usado.

last_used_atstring

Último uso, em RFC 3339 (UTC). Vazio se nunca foi usado.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON (validação)	`{"message":"Invalid JSON body","status":400}`
400	`cart_total` inválido (validação)	`{"message":"Invalid cart_total: ...","status":400}`
401	Sem credenciais	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Uso por quem não é administrador	`{"message":"Forbidden: financial data requires admin scope","status":403}`
404	Código sem cupom ativo (uso)	`{"message":"Coupon code not found","status":404}`

Veja também

Rotas de cupons

Valida um cupom contra um carrinho e consulta o uso de um cupom.

POST/api/v1.0/coupons/{code}/validateAutenticada

Validar um cupom contra um carrinho

Parâmetros de caminho

codestringobrigatório

Código do cupom.

Corpo da requisição

cart_totalstringobrigatório

Total do carrinho em decimal com ponto, em reais ("150.00").

user_idstring

Id do cliente, quando o cupom tem regra por cliente.

itemsarray

Itens do carrinho, usados por cupons com condição de produto, categoria ou seller.

product_idstring

Id do produto.

category_idstring

Id da categoria principal.

category_idsarray

Todas as categorias do produto. Quando vem, tem preferência sobre category_id.

vendor_idstring

Id do seller.

quantityinteger

Quantidade.

pricestring

Preço unitário em decimal com ponto ("89.90").

GET/api/v1.0/coupons/{code}/usageAdmin

Consultar o uso de um cupom

Devolve o resumo de uso de um cupom ativo: quantos usos, quantos clientes diferentes, quanto desconto foi dado e quando foi usado pela primeira e pela última vez.

Parâmetros de caminho

codestringobrigatório

Código do cupom.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/coupons/BEMVINDO10/validate" \
  -H "Content-Type: application/json" \
  -d '{"cart_total":"150.00","items":[{"product_id":"d8a6c5e7-8e44-4055-a0e2-49014f5d17f6","quantity":1,"price":"150.00"}]}'

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/coupons/BEMVINDO10/usage"

Resposta

200Cupom que não vale

json

{
  "applies_to": "cart",
  "code": "nope",
  "discount_amount": "0.00",
  "discount_type": "",
  "message": "cupom não encontrado ou inativo",
  "promotion_id": "",
  "valid": false
}

200Uso do cupom

json

{
  "code": "bemvindo10",
  "promotion_id": "2b6f1c5e-8d3a-4f6e-9a0b-6c1d7e2f3a44",
  "promotion_name": "10% no primeiro pedido",
  "max_uses": 100,
  "total_uses": 12,
  "remaining": 88,
  "unique_users": 12,
  "total_discount_given": "184.50",
  "first_used_at": "2026-10-02T13:05:11Z",
  "last_used_at": "2026-10-11T18:42:07Z"
}

Campos da resposta

codestring

Código do cupom, em minúscula.

validboolean

true quando o cupom se aplica ao carrinho.

discount_amountstring

Desconto em decimal ("15.00"). "0.00" quando não vale.

discount_typestring

Tipo do desconto da promoção; vazio quando não vale.

applies_tostring

Onde o desconto incide; hoje cart.

promotion_idstring

Id da promoção do cupom; vazio quando não vale.

promotion_namestring

Nome da promoção.

messagestring

Motivo, em português, quando o cupom não vale. A mensagem vem como o servidor a devolve.

max_usesinteger

Limite de usos; 0 sem limite.

total_usesinteger

Usos até agora.

remaininginteger

Usos que faltam; -1 quando não há limite.

unique_usersinteger

Clientes diferentes que usaram.

total_discount_givenstring

Soma dos descontos dados, em decimal.

first_used_atstring

Primeiro uso, em RFC 3339 (UTC). Vazio se nunca foi usado.

last_used_atstring

Último uso, em RFC 3339 (UTC). Vazio se nunca foi usado.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON (validação)	`{"message":"Invalid JSON body","status":400}`
400	`cart_total` inválido (validação)	`{"message":"Invalid cart_total: ...","status":400}`
401	Sem credenciais	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Uso por quem não é administrador	`{"message":"Forbidden: financial data requires admin scope","status":403}`
404	Código sem cupom ativo (uso)	`{"message":"Coupon code not found","status":404}`