API atual/Referência completa/Promoções e cupons

Cupons

Define o código de uma promoção, gera códigos descartáveis e simula a validade de um cupom.

No modelo da plataforma o cupom é a promoção: o código fica no campo code dela. Estas rotas são atalhos para trabalhar com o código. Se a loja desligou o recurso de cupons (em Personalizações), elas respondem 403 com o nome do recurso, e promoções que exigem código deixam de aparecer na vitrine.

Ver o cupom de uma promoção

GET/api/v1/admin/promotions/{id}/couponsAdmin

Mostra o cupom (código e uso) de uma promoção

Parâmetros de caminho

iduuidobrigatório

Id da promoção.

Exemplo de requisição: ver cupom

bash

curl "$BASE_URL/api/v1/admin/promotions/7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30/coupons" \
  -H "Authorization: Bearer $TOKEN"

Resposta: ver cupom

200Cupom da promoção

json

{
  "coupons": [
    {
      "code": "BLACK10",
      "usage_count": 12,
      "usage_limit": 500,
      "status": "A"
    }
  ],
  "total": 1
}

Campos da resposta

couponsarray

Zero ou um item. Vem null quando a promoção não tem código.

codestring

O código.

usage_countinteger

Usos até agora.

usage_limitinteger

Limite de usos, 0 = sem limite.

statusstring

Letra de status da promoção.

totalinteger

Quantidade de itens em coupons (0 ou 1).

Erros: ver cupom

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	Id não é UUID completo.	`{"error":"invalid id","detail":"..."}`
404	Promoção inexistente.	`{"error":"promotion not found"}`

Definir o código de uma promoção

POST/api/v1/admin/promotions/{id}/couponsAdmin

Define o código de uma promoção que ainda não tem um

Parâmetros de caminho

iduuidobrigatório

Id da promoção.

Corpo da requisição

codestringobrigatório

O código. Vira maiúsculo.

max_usesinteger

Define usage_limit da promoção.

Exemplo de requisição: definir código

bash

curl -X POST "$BASE_URL/api/v1/admin/promotions/7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30/coupons" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BLACK10",
    "max_uses": 500
  }'

Resposta: definir código

201Código definido

json

{
  "code": "BLACK10",
  "usage_count": 0,
  "usage_limit": 500,
  "status": "A"
}

Erros: definir código

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	`code` ausente, corpo inválido ou id inválido.	`{"error":"code is required"}`
404	Promoção inexistente.	`{"error":"promotion not found"}`
409	A promoção já tem código. A resposta traz o código atual em `code`.	`{"error":"coupon_already_exists","message":"a coupon code is already set on this promotion ...","code":"BLACK10"}`

Gerar códigos descartáveis

POST/api/v1/admin/promotions/generate-auto-couponsAdmin

Gera códigos únicos a partir de uma promoção-modelo

Corpo da requisição

promotion_iduuidobrigatório

Promoção-modelo, de onde vêm desconto, condições e bônus.

countintegerpadrão: 1

Quantos códigos gerar, de 1 a 1000.

prefixstringpadrão: PROMO

Prefixo do código, em maiúsculas. O formato é PREFIXO-A3B4C5.

Exemplo de requisição: gerar

bash

curl -X POST "$BASE_URL/api/v1/admin/promotions/generate-auto-coupons" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "promotion_id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
    "count": 3,
    "prefix": "VIP"
  }'

Resposta: gerar

201Códigos gerados

json

{
  "codes": ["VIP-3F9A1C", "VIP-B02E77", "VIP-91D4A8"],
  "count": 3,
  "promotion_id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30"
}

Campos da resposta

codesarray of string

Os códigos criados.

countinteger

Quantos foram criados.

promotion_iduuid

A promoção-modelo.

Erros: gerar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	`promotion_id` ausente ou inválido, ou `count` acima de 1000.	`{"error":"count must be between 1 and 1000"}`
500	Promoção-modelo não existe, ou o escopo dela aponta para algo que não existe mais.	`{"error":"failed to generate coupons","detail":"promotion not found: ..."}`

Simular um cupom

POST/api/v1/admin/coupons/validateAdmin

Simula se um código seria aceito e que desconto daria

Corpo da requisição

codestringobrigatório

O código, sem diferenciar maiúsculas.

cart_totalinteger

Subtotal do carrinho simulado, em centavos.

customer_emailstring

Aceito, mas hoje não influencia o resultado.

Exemplo de requisição: simular

bash

curl -X POST "$BASE_URL/api/v1/admin/coupons/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BLACK10",
    "cart_total": 30000
  }'

Resposta: simular

200Cupom aplicável

json

{
  "applicable": true,
  "promotion_id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "discount": 3000,
  "discount_type": "percentage",
  "free_shipping": false,
  "stop_other_rules": false,
  "reason": "promotion applied successfully"
}

200Cupom não aplicável

json

{
  "applicable": false,
  "discount": 0,
  "discount_type": "",
  "free_shipping": false,
  "stop_other_rules": false,
  "reason": "cupom não encontrado ou inativo"
}

Campos da resposta

applicableboolean

Se o código seria aceito.

promotion_iduuid | omitted

Promoção dona do código.

discountinteger

Desconto calculado, em centavos, sobre o cart_total informado.

discount_typestring

Tipo da promoção.

free_shippingboolean

Se concede frete grátis.

stop_other_rulesboolean

Se interrompe as demais promoções.

reasonstring

Explicação em português do resultado (por exemplo "esta promoção expirou", "limite de uso desta promoção foi atingido").

Erros: simular

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	`code` ausente ou corpo inválido.	`{"error":"code is required"}`

Veja também

API atual/Referência completa/Promoções e cupons

Cupons

Define o código de uma promoção, gera códigos descartáveis e simula a validade de um cupom.

Ver o cupom de uma promoção

GET/api/v1/admin/promotions/{id}/couponsAdmin

Mostra o cupom (código e uso) de uma promoção

Parâmetros de caminho

iduuidobrigatório

Id da promoção.

Exemplo de requisição: ver cupom

bash

curl "$BASE_URL/api/v1/admin/promotions/7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30/coupons" \
  -H "Authorization: Bearer $TOKEN"

Resposta: ver cupom

200Cupom da promoção

json

{
  "coupons": [
    {
      "code": "BLACK10",
      "usage_count": 12,
      "usage_limit": 500,
      "status": "A"
    }
  ],
  "total": 1
}

Campos da resposta

couponsarray

Zero ou um item. Vem null quando a promoção não tem código.

codestring

O código.

usage_countinteger

Usos até agora.

usage_limitinteger

Limite de usos, 0 = sem limite.

statusstring

Letra de status da promoção.

totalinteger

Quantidade de itens em coupons (0 ou 1).

Erros: ver cupom

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	Id não é UUID completo.	`{"error":"invalid id","detail":"..."}`
404	Promoção inexistente.	`{"error":"promotion not found"}`

Definir o código de uma promoção

POST/api/v1/admin/promotions/{id}/couponsAdmin

Define o código de uma promoção que ainda não tem um

Parâmetros de caminho

iduuidobrigatório

Id da promoção.

Corpo da requisição

codestringobrigatório

O código. Vira maiúsculo.

max_usesinteger

Define usage_limit da promoção.

Exemplo de requisição: definir código

bash

curl -X POST "$BASE_URL/api/v1/admin/promotions/7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30/coupons" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BLACK10",
    "max_uses": 500
  }'

Resposta: definir código

201Código definido

json

{
  "code": "BLACK10",
  "usage_count": 0,
  "usage_limit": 500,
  "status": "A"
}

Erros: definir código

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	`code` ausente, corpo inválido ou id inválido.	`{"error":"code is required"}`
404	Promoção inexistente.	`{"error":"promotion not found"}`
409	A promoção já tem código. A resposta traz o código atual em `code`.	`{"error":"coupon_already_exists","message":"a coupon code is already set on this promotion ...","code":"BLACK10"}`

Gerar códigos descartáveis

POST/api/v1/admin/promotions/generate-auto-couponsAdmin

Gera códigos únicos a partir de uma promoção-modelo

Corpo da requisição

promotion_iduuidobrigatório

Promoção-modelo, de onde vêm desconto, condições e bônus.

countintegerpadrão: 1

Quantos códigos gerar, de 1 a 1000.

prefixstringpadrão: PROMO

Prefixo do código, em maiúsculas. O formato é PREFIXO-A3B4C5.

Exemplo de requisição: gerar

bash

curl -X POST "$BASE_URL/api/v1/admin/promotions/generate-auto-coupons" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "promotion_id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
    "count": 3,
    "prefix": "VIP"
  }'

Resposta: gerar

201Códigos gerados

json

{
  "codes": ["VIP-3F9A1C", "VIP-B02E77", "VIP-91D4A8"],
  "count": 3,
  "promotion_id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30"
}

Campos da resposta

codesarray of string

Os códigos criados.

countinteger

Quantos foram criados.

promotion_iduuid

A promoção-modelo.

Erros: gerar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	`promotion_id` ausente ou inválido, ou `count` acima de 1000.	`{"error":"count must be between 1 and 1000"}`
500	Promoção-modelo não existe, ou o escopo dela aponta para algo que não existe mais.	`{"error":"failed to generate coupons","detail":"promotion not found: ..."}`

Simular um cupom

POST/api/v1/admin/coupons/validateAdmin

Simula se um código seria aceito e que desconto daria

Corpo da requisição

codestringobrigatório

O código, sem diferenciar maiúsculas.

cart_totalinteger

Subtotal do carrinho simulado, em centavos.

customer_emailstring

Aceito, mas hoje não influencia o resultado.

Exemplo de requisição: simular

bash

curl -X POST "$BASE_URL/api/v1/admin/coupons/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "BLACK10",
    "cart_total": 30000
  }'

Resposta: simular

200Cupom aplicável

json

{
  "applicable": true,
  "promotion_id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "discount": 3000,
  "discount_type": "percentage",
  "free_shipping": false,
  "stop_other_rules": false,
  "reason": "promotion applied successfully"
}

200Cupom não aplicável

json

{
  "applicable": false,
  "discount": 0,
  "discount_type": "",
  "free_shipping": false,
  "stop_other_rules": false,
  "reason": "cupom não encontrado ou inativo"
}

Campos da resposta

applicableboolean

Se o código seria aceito.

promotion_iduuid | omitted

Promoção dona do código.

discountinteger

Desconto calculado, em centavos, sobre o cart_total informado.

discount_typestring

Tipo da promoção.

free_shippingboolean

Se concede frete grátis.

stop_other_rulesboolean

Se interrompe as demais promoções.

reasonstring

Explicação em português do resultado (por exemplo "esta promoção expirou", "limite de uso desta promoção foi atingido").

Erros: simular

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	`code` ausente ou corpo inválido.	`{"error":"code is required"}`