🎟️ Documentação de Cupons

📋 Visão Geral

Um cupom é um código promocional que o cliente aplica no carrinho para ativar um desconto.

Cada cupom está obrigatoriamente vinculado a uma entidade promocional que define o tipo, o alvo e o valor do benefício. O campo hash é o código digitado pelo cliente — deve ser único na loja.

🔄 Entidades Envolvidas

Todo cupom está vinculado a uma Entidade Promocional (promotionalEntityId), que define o comportamento base do desconto — incluindo o campo avaliado (itemField), o tipo de desconto (type) e o alvo (target).

Os campos opcionais do cupom representam módulos independentes:

Agendamento (scheduling) — define o período de vigência do cupom com datas de início e fim.
Segmentação (segmentation) — determina quais clientes ou contextos de venda são elegíveis, com regras combinadas por operador lógico.
Descontos (discounts) — detalha os valores aplicados por entidade, incluindo itemAmount e value.

📌 Notas e Considerações

O campo hash é gerado automaticamente com 8 caracteres alfanuméricos em minúsculo caso não seja informado. Deve ser único na loja — duplicatas retornam o erro UAPPI_STORE_COUPON_HASH_ALREADY_IN_USE.
Cupons clonados recebem um hash no formato {hashOriginal}-{8chars} e podem manter referência ao cupom de origem via parentCouponId conforme o parâmetro preserveParent.
Não é possível clonar um cupom já clonado — tentativas retornam o erro UAPPI_STORE_COUPON_IS_CLONE.
Os campos scheduling, segmentation e discounts retornam null por padrão. Para carregá-los, informe-os no parâmetro fields da requisição.
Pedidos cancelados não são contabilizados nas verificações de minCustomerPurchaseQuantity e maxCustomerPurchaseQuantity.

📋 Listagem de Cupons

GET /promotionals/coupons

Retorna a listagem paginada de cupons cadastrados na loja

📋 Descrição

Endpoint utilizado para listar todos os cupons cadastrados na loja, com suporte a paginação, filtros e ordenação.

Por padrão, os campos scheduling, segmentation e discounts retornam como null. Informe-os no parâmetro fields quando precisar exibir informações detalhadas de cada cupom na listagem.

Requer o escopo COUPON_READ.

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer SEU_TOKEN_AQUI	Token de autenticação

🗂️ Campos Disponíveis (fields)

Campo	Descrição
scheduling	Agendamento do cupom (período de vigência)
segmentation	Segmentação e regras de elegibilidade
discounts	Descontos associados ao cupom

🔍 Campos de Condição Disponíveis

Campo	Tipo	Descrição
userId	integer	ID do usuário (filtro interno)
active	boolean	Status de ativação do cupom
hash	string	Código do cupom
title	string	Título da entidade promocional vinculada
type	string	Tipo de desconto da entidade
target	string	Alvo do desconto
itemField	string	Campo avaliado no desconto
parentCouponId	integer	ID do cupom de origem (presente em clones)
allowWithPromotion	boolean	Permite uso simultâneo com promoções
tradePolicyId	integer	ID da política comercial

🔃 Campos de Ordenação Disponíveis

Campo	Descrição
id	ID do cupom
couponId	ID do cupom (alias)
title	Título da entidade promocional
createdAt	Data de criação

💡 Exemplo de Requisição

> Nota: esta API aceita corpo JSON em requisições GET, seguindo a convenção da plataforma. Utilize o header Content-Type: application/json e envie os parâmetros no corpo da requisição.

1curl --request GET \
2  --url {{MAIN_URL}}/promotionals/coupons \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "fields": ["scheduling", "segmentation", "discounts"],
7    "limit": 10,
8    "offset": 0
9  }'
curl --request GET \
  --url {{MAIN_URL}}/promotionals/coupons \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "fields": ["scheduling", "segmentation", "discounts"],
    "limit": 10,
    "offset": 0
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 1,
7        "parentCouponId": null,
8        "entity": {
9          "title": "Desconto Verão 10%",
10          "observation": null,
11          "itemField": "value",
12          "type": "percentage",
13          "target": "subtotal-shipping",
14          "active": true,
15          "tradePolicies": [1],
16          "id": 5,
17          "createdAt": "2026-03-01 09:00:00",
18          "updatedAt": "2026-03-01 09:00:00"
19        },
20        "hash": "verao10",
21        "quantityUsed": 12,
22        "maxQuantityUse": 100,
23        "maxQuantityCustomerUse": 1,
24        "minCustomerPurchaseQuantity": 0,
25        "maxCustomerPurchaseQuantity": 0,
26        "allowWithPromotion": false,
27        "scheduling": null,
28        "segmentation": null,
29        "discounts": [
30          {
31            "entityId": 1,
32            "entity": "coupon",
33            "itemAmount": 1,
34            "value": 10
35          }
36        ],
37        "createdAt": "2026-03-01 09:00:00",
38        "updatedAt": "2026-03-15 14:20:00"
39      }
40    ],
41    "pagination": {
42      "limit": 10,
43      "offset": 0,
44      "pages": 1,
45      "registers": 1
46    }
47  }
48}
{
  "status": true,
  "data": {
    "registers": [
      {
        "id": 1,
        "parentCouponId": null,
        "entity": {
          "title": "Desconto Verão 10%",
          "observation": null,
          "itemField": "value",
          "type": "percentage",
          "target": "subtotal-shipping",
          "active": true,
          "tradePolicies": [1],
          "id": 5,
          "createdAt": "2026-03-01 09:00:00",
          "updatedAt": "2026-03-01 09:00:00"
        },
        "hash": "verao10",
        "quantityUsed": 12,
        "maxQuantityUse": 100,
        "maxQuantityCustomerUse": 1,
        "minCustomerPurchaseQuantity": 0,
        "maxCustomerPurchaseQuantity": 0,
        "allowWithPromotion": false,
        "scheduling": null,
        "segmentation": null,
        "discounts": [
          {
            "entityId": 1,
            "entity": "coupon",
            "itemAmount": 1,
            "value": 10
          }
        ],
        "createdAt": "2026-03-01 09:00:00",
        "updatedAt": "2026-03-15 14:20:00"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "pages": 1,
      "registers": 1
    }
  }
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `COUPON_READ`.

🔍 Detalhamento de Cupom

GET /promotionals/coupons/{couponId}

Retorna os dados completos de um cupom pelo seu ID

📋 Descrição

Endpoint utilizado para carregar os dados completos de um cupom no painel administrativo, identificado pelo couponId na URL.

Os campos opcionais scheduling, segmentation e discounts retornam null por padrão. Para carregá-los, informe-os no parâmetro fields — útil para exibir detalhes completos do cupom em telas de edição.

Caso o cupom não seja encontrado, o endpoint retorna erro 400 com o código UAPPI_STORE_COUPON_NOT_FOUND.

Requer o escopo COUPON_READ.

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer SEU_TOKEN_AQUI	Token de autenticação

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
couponId	integer	✅ Sim	ID do cupom a ser detalhado

🗂️ Campos Disponíveis (fields)

Campo	Descrição
scheduling	Agendamento do cupom (período de vigência)
segmentation	Segmentação e regras de elegibilidade
discounts	Descontos associados ao cupom

💡 Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/promotionals/coupons/1 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "fields": ["scheduling", "segmentation", "discounts"]
7  }'
curl --request GET \
  --url {{MAIN_URL}}/promotionals/coupons/1 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "fields": ["scheduling", "segmentation", "discounts"]
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "parentCouponId": null,
6    "entity": {
7      "title": "Desconto Verão 10%",
8      "observation": null,
9      "itemField": "value",
10      "type": "percentage",
11      "target": "subtotal-shipping",
12      "active": true,
13      "tradePolicies": [1],
14      "id": 5,
15      "createdAt": "2026-03-01 09:00:00",
16      "updatedAt": "2026-03-01 09:00:00"
17    },
18    "hash": "verao10",
19    "quantityUsed": 12,
20    "maxQuantityUse": 100,
21    "maxQuantityCustomerUse": 1,
22    "minCustomerPurchaseQuantity": 0,
23    "maxCustomerPurchaseQuantity": 0,
24    "allowWithPromotion": false,
25    "scheduling": {
26      "id": 3,
27      "startsAt": "2026-06-01 00:00:00",
28      "endsAt": "2026-08-31 23:59:59"
29    },
30    "segmentation": {
31      "id": 2,
32      "operator": "and",
33      "sellerId": null,
34      "userForAllSellers": false,
35      "rules": [
36        {
37          "id": 4,
38          "ruleType": "customer-age",
39          "ruleOperator": "greater",
40          "ruleValue": 18,
41          "entityMap": null,
42          "createdAt": "2026-03-01 09:00:00",
43          "updatedAt": "2026-03-01 09:00:00"
44        }
45      ],
46      "entityMap": null
47    },
48    "discounts": [
49      {
50        "entityId": 1,
51        "entity": "coupon",
52        "itemAmount": 1,
53        "value": 10
54      }
55    ],
56    "createdAt": "2026-03-01 09:00:00",
57    "updatedAt": "2026-03-15 14:20:00"
58  }
59}
{
  "status": true,
  "data": {
    "id": 1,
    "parentCouponId": null,
    "entity": {
      "title": "Desconto Verão 10%",
      "observation": null,
      "itemField": "value",
      "type": "percentage",
      "target": "subtotal-shipping",
      "active": true,
      "tradePolicies": [1],
      "id": 5,
      "createdAt": "2026-03-01 09:00:00",
      "updatedAt": "2026-03-01 09:00:00"
    },
    "hash": "verao10",
    "quantityUsed": 12,
    "maxQuantityUse": 100,
    "maxQuantityCustomerUse": 1,
    "minCustomerPurchaseQuantity": 0,
    "maxCustomerPurchaseQuantity": 0,
    "allowWithPromotion": false,
    "scheduling": {
      "id": 3,
      "startsAt": "2026-06-01 00:00:00",
      "endsAt": "2026-08-31 23:59:59"
    },
    "segmentation": {
      "id": 2,
      "operator": "and",
      "sellerId": null,
      "userForAllSellers": false,
      "rules": [
        {
          "id": 4,
          "ruleType": "customer-age",
          "ruleOperator": "greater",
          "ruleValue": 18,
          "entityMap": null,
          "createdAt": "2026-03-01 09:00:00",
          "updatedAt": "2026-03-01 09:00:00"
        }
      ],
      "entityMap": null
    },
    "discounts": [
      {
        "entityId": 1,
        "entity": "coupon",
        "itemAmount": 1,
        "value": 10
      }
    ],
    "createdAt": "2026-03-01 09:00:00",
    "updatedAt": "2026-03-15 14:20:00"
  }
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `COUPON_READ`.
UAPPI_STORE_COUPON_NOT_FOUND	400	❌ O cupom informado não foi encontrado.

➕ Criação de Cupom

POST /promotionals/coupons

Permite criar um novo cupom promocional na loja

📋 Descrição

Endpoint responsável por criar um novo cupom promocional, vinculado a uma entidade promocional (promotionalEntityId) existente.

O campo hash é o código que o cliente digita para ativar o desconto. Quando não informado, é gerado automaticamente com 8 caracteres alfanuméricos em minúsculo. Deve ser único na loja.

Os campos maxQuantityUse e maxQuantityCustomerUse controlam os limites de uso. Os campos minCustomerPurchaseQuantity e maxCustomerPurchaseQuantity restringem o cupom por histórico de pedidos do cliente — o valor 0 desativa a restrição e pedidos cancelados não são contabilizados.

Após a criação, a resposta retorna o cupom com scheduling, segmentation e discounts sempre carregados (podendo ser null ou array vazio).

Requer os escopos COUPON_READ e COUPON_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer SEU_TOKEN_AQUI	Token de autenticação

📦 Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
promotionalEntityId	integer	✅ Sim	ID da entidade promocional à qual o cupom será vinculado
maxQuantityUse	integer	✅ Sim	Limite global de utilizações do cupom
maxQuantityCustomerUse	integer	✅ Sim	Limite de utilizações por cliente
minCustomerPurchaseQuantity	integer	✅ Sim	Mínimo de pedidos realizados pelo cliente (`0` = sem restrição)
maxCustomerPurchaseQuantity	integer	✅ Sim	Máximo de pedidos realizados pelo cliente (`0` = sem restrição)
allowWithPromotion	boolean	✅ Sim	Permite uso simultâneo com promoções ativas
hash	string	❌ Não	Código do cupom (máximo 100 caracteres). Gerado automaticamente se omitido

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/promotionals/coupons \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "promotionalEntityId": 5,
7    "hash": "verao10",
8    "maxQuantityUse": 100,
9    "maxQuantityCustomerUse": 1,
10    "minCustomerPurchaseQuantity": 0,
11    "maxCustomerPurchaseQuantity": 0,
12    "allowWithPromotion": false
13  }'
curl --request POST \
  --url {{MAIN_URL}}/promotionals/coupons \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "promotionalEntityId": 5,
    "hash": "verao10",
    "maxQuantityUse": 100,
    "maxQuantityCustomerUse": 1,
    "minCustomerPurchaseQuantity": 0,
    "maxCustomerPurchaseQuantity": 0,
    "allowWithPromotion": false
  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 7,
5    "parentCouponId": null,
6    "entity": {
7      "title": "Desconto Verão 10%",
8      "observation": null,
9      "itemField": "value",
10      "type": "percentage",
11      "target": "subtotal-shipping",
12      "active": true,
13      "tradePolicies": [1],
14      "id": 5,
15      "createdAt": "2026-03-01 09:00:00",
16      "updatedAt": "2026-03-01 09:00:00"
17    },
18    "hash": "verao10",
19    "quantityUsed": 0,
20    "maxQuantityUse": 100,
21    "maxQuantityCustomerUse": 1,
22    "minCustomerPurchaseQuantity": 0,
23    "maxCustomerPurchaseQuantity": 0,
24    "allowWithPromotion": false,
25    "scheduling": null,
26    "segmentation": null,
27    "discounts": [],
28    "createdAt": "2026-05-06 10:00:00",
29    "updatedAt": "2026-05-06 10:00:00"
30  }
31}
{
  "status": true,
  "data": {
    "id": 7,
    "parentCouponId": null,
    "entity": {
      "title": "Desconto Verão 10%",
      "observation": null,
      "itemField": "value",
      "type": "percentage",
      "target": "subtotal-shipping",
      "active": true,
      "tradePolicies": [1],
      "id": 5,
      "createdAt": "2026-03-01 09:00:00",
      "updatedAt": "2026-03-01 09:00:00"
    },
    "hash": "verao10",
    "quantityUsed": 0,
    "maxQuantityUse": 100,
    "maxQuantityCustomerUse": 1,
    "minCustomerPurchaseQuantity": 0,
    "maxCustomerPurchaseQuantity": 0,
    "allowWithPromotion": false,
    "scheduling": null,
    "segmentation": null,
    "discounts": [],
    "createdAt": "2026-05-06 10:00:00",
    "updatedAt": "2026-05-06 10:00:00"
  }
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `COUPON_WRITE`.
UAPPI_STORE_COUPON_HASH_ALREADY_IN_USE	400	❌ O hash informado já está em uso por outro cupom.
UAPPI_STORE_PROMOTIONAL_ENTITY_NOT_FOUND	400	❌ A entidade promocional informada não foi encontrada.

✏️ Atualização de Cupom

PUT /promotionals/coupons/{couponId}

Atualiza os dados de um cupom existente

📋 Descrição

Endpoint responsável por atualizar um cupom existente, identificado pelo couponId na URL.

A operação é um update completo — todos os campos obrigatórios devem ser enviados mesmo que não tenham sido alterados. O campo hash pode ser alterado, desde que o novo valor seja único na loja.

Caso o cupom não seja encontrado, o retorno é um erro 400 com o código UAPPI_STORE_COUPON_NOT_FOUND.

Requer os escopos COUPON_READ e COUPON_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer SEU_TOKEN_AQUI	Token de autenticação

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
couponId	integer	✅ Sim	ID do cupom a ser atualizado

📦 Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
promotionalEntityId	integer	✅ Sim	ID da entidade promocional vinculada ao cupom
maxQuantityUse	integer	✅ Sim	Limite global de utilizações do cupom
maxQuantityCustomerUse	integer	✅ Sim	Limite de utilizações por cliente
minCustomerPurchaseQuantity	integer	✅ Sim	Mínimo de pedidos realizados pelo cliente (`0` = sem restrição)
maxCustomerPurchaseQuantity	integer	✅ Sim	Máximo de pedidos realizados pelo cliente (`0` = sem restrição)
allowWithPromotion	boolean	✅ Sim	Permite uso simultâneo com promoções ativas
hash	string	❌ Não	Código do cupom (máximo 100 caracteres). Gerado automaticamente se omitido

💡 Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/promotionals/coupons/7 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "promotionalEntityId": 5,
7    "hash": "verao10-vip",
8    "maxQuantityUse": 50,
9    "maxQuantityCustomerUse": 2,
10    "minCustomerPurchaseQuantity": 1,
11    "maxCustomerPurchaseQuantity": 0,
12    "allowWithPromotion": true
13  }'
curl --request PUT \
  --url {{MAIN_URL}}/promotionals/coupons/7 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "promotionalEntityId": 5,
    "hash": "verao10-vip",
    "maxQuantityUse": 50,
    "maxQuantityCustomerUse": 2,
    "minCustomerPurchaseQuantity": 1,
    "maxCustomerPurchaseQuantity": 0,
    "allowWithPromotion": true
  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 7,
5    "parentCouponId": null,
6    "entity": {
7      "title": "Desconto Verão 10%",
8      "observation": null,
9      "itemField": "value",
10      "type": "percentage",
11      "target": "subtotal-shipping",
12      "active": true,
13      "tradePolicies": [1],
14      "id": 5,
15      "createdAt": "2026-03-01 09:00:00",
16      "updatedAt": "2026-03-01 09:00:00"
17    },
18    "hash": "verao10-vip",
19    "quantityUsed": 12,
20    "maxQuantityUse": 50,
21    "maxQuantityCustomerUse": 2,
22    "minCustomerPurchaseQuantity": 1,
23    "maxCustomerPurchaseQuantity": 0,
24    "allowWithPromotion": true,
25    "scheduling": null,
26    "segmentation": null,
27    "discounts": [],
28    "createdAt": "2026-05-06 10:00:00",
29    "updatedAt": "2026-05-06 11:30:00"
30  }
31}
{
  "status": true,
  "data": {
    "id": 7,
    "parentCouponId": null,
    "entity": {
      "title": "Desconto Verão 10%",
      "observation": null,
      "itemField": "value",
      "type": "percentage",
      "target": "subtotal-shipping",
      "active": true,
      "tradePolicies": [1],
      "id": 5,
      "createdAt": "2026-03-01 09:00:00",
      "updatedAt": "2026-03-01 09:00:00"
    },
    "hash": "verao10-vip",
    "quantityUsed": 12,
    "maxQuantityUse": 50,
    "maxQuantityCustomerUse": 2,
    "minCustomerPurchaseQuantity": 1,
    "maxCustomerPurchaseQuantity": 0,
    "allowWithPromotion": true,
    "scheduling": null,
    "segmentation": null,
    "discounts": [],
    "createdAt": "2026-05-06 10:00:00",
    "updatedAt": "2026-05-06 11:30:00"
  }
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `COUPON_WRITE`.
UAPPI_STORE_COUPON_NOT_FOUND	400	❌ O cupom informado não foi encontrado.
UAPPI_STORE_COUPON_HASH_ALREADY_IN_USE	400	❌ O hash informado já está em uso por outro cupom.
UAPPI_STORE_PROMOTIONAL_ENTITY_NOT_FOUND	400	❌ A entidade promocional informada não foi encontrada.

🔁 Clonagem de Cupom

POST /promotionals/coupons/{couponId}/clone

Clona um cupom existente, gerando cópias com hashes únicos

📋 Descrição

Endpoint responsável por clonar um cupom existente, gerando uma ou mais cópias com hashes únicos derivados do cupom de origem.

Cada clone herda todas as configurações do cupom original — promotionalEntityId, limites de uso, allowWithPromotion e os descontos vinculados. O novo hash segue o formato {hashOriginal}-{8chars}.

O parâmetro preserveParent controla se os clones mantêm referência ao cupom de origem via parentCouponId: true registra o ID do original, false cria os clones sem vínculo de parentesco.

Não é possível clonar um cupom que já seja um clone — cupons com parentCouponId preenchido retornam o erro UAPPI_STORE_COUPON_IS_CLONE. A resposta retorna os dados do cupom de origem, não dos clones gerados. O limite máximo é de 50 cópias por operação.

Requer os escopos COUPON_READ e COUPON_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer SEU_TOKEN_AQUI	Token de autenticação

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
couponId	integer	✅ Sim	ID do cupom a ser clonado

📦 Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
quantity	integer	✅ Sim	Número de cópias a serem geradas (mínimo: 1, máximo: 50)
preserveParent	boolean	✅ Sim	Indica se os clones devem referenciar o cupom original via `parentCouponId`

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/promotionals/coupons/7/clone \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "quantity": 3,
7    "preserveParent": true
8  }'
curl --request POST \
  --url {{MAIN_URL}}/promotionals/coupons/7/clone \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "quantity": 3,
    "preserveParent": true
  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

> A resposta retorna os dados do cupom de origem, não dos clones gerados.

1{
2  "status": true,
3  "data": {
4    "id": 7,
5    "parentCouponId": null,
6    "entity": {
7      "title": "Desconto Verão 10%",
8      "observation": null,
9      "itemField": "value",
10      "type": "percentage",
11      "target": "subtotal-shipping",
12      "active": true,
13      "tradePolicies": [1],
14      "id": 5,
15      "createdAt": "2026-03-01 09:00:00",
16      "updatedAt": "2026-03-01 09:00:00"
17    },
18    "hash": "verao10",
19    "quantityUsed": 0,
20    "maxQuantityUse": 100,
21    "maxQuantityCustomerUse": 1,
22    "minCustomerPurchaseQuantity": 0,
23    "maxCustomerPurchaseQuantity": 0,
24    "allowWithPromotion": false,
25    "scheduling": null,
26    "segmentation": null,
27    "discounts": [],
28    "createdAt": "2026-05-06 10:00:00",
29    "updatedAt": "2026-05-06 10:00:00"
30  }
31}
{
  "status": true,
  "data": {
    "id": 7,
    "parentCouponId": null,
    "entity": {
      "title": "Desconto Verão 10%",
      "observation": null,
      "itemField": "value",
      "type": "percentage",
      "target": "subtotal-shipping",
      "active": true,
      "tradePolicies": [1],
      "id": 5,
      "createdAt": "2026-03-01 09:00:00",
      "updatedAt": "2026-03-01 09:00:00"
    },
    "hash": "verao10",
    "quantityUsed": 0,
    "maxQuantityUse": 100,
    "maxQuantityCustomerUse": 1,
    "minCustomerPurchaseQuantity": 0,
    "maxCustomerPurchaseQuantity": 0,
    "allowWithPromotion": false,
    "scheduling": null,
    "segmentation": null,
    "discounts": [],
    "createdAt": "2026-05-06 10:00:00",
    "updatedAt": "2026-05-06 10:00:00"
  }
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `COUPON_WRITE`.
UAPPI_STORE_COUPON_NOT_FOUND	400	❌ O cupom informado não foi encontrado.
UAPPI_STORE_COUPON_IS_CLONE	400	❌ Não é possível clonar um cupom que já é um clone.

🗑️ Exclusão de Cupom

DELETE /promotionals/coupons/{couponId}

Remove permanentemente um cupom da loja

📋 Descrição

Endpoint responsável por remover permanentemente um cupom, identificado pelo couponId na URL.

Quando o cupom removido é o único vinculado à entidade promocional, a entidade e seus dados de agendamento e segmentação também são excluídos automaticamente. Caso a entidade possua outros cupons, ela é preservada.

Quando a exclusão é bem-sucedida, o campo data retorna true.

Requer os escopos COUPON_READ e COUPON_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

Header	Valor	Descrição
Content-Type	application/json	Tipo de conteúdo
Authorization	Bearer SEU_TOKEN_AQUI	Token de autenticação

🔑 Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
couponId	integer	✅ Sim	ID do cupom a ser removido

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/promotionals/coupons/7 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"
curl --request DELETE \
  --url {{MAIN_URL}}/promotionals/coupons/7 \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": true
4}
{
  "status": true,
  "data": true
}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código Interno	HTTP	Descrição
UAPPI_AUTH_INVALID	401	❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED	403	❌ O usuário não possui a permissão `COUPON_WRITE`.
UAPPI_STORE_COUPON_NOT_FOUND	400	❌ O cupom informado não foi encontrado.

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

🎟️ Documentação de Cupons

📋 Visão Geral

🔄 Entidades Envolvidas

📌 Notas e Considerações

📋 Listagem de Cupons

📋 Descrição

📝 Parâmetros

🏷️ Headers Obrigatórios

🗂️ Campos Disponíveis (fields)

🔍 Campos de Condição Disponíveis

🔃 Campos de Ordenação Disponíveis

💡 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis Erros

🔍 Detalhamento de Cupom

📋 Descrição

📝 Parâmetros

🏷️ Headers Obrigatórios

🔑 Parâmetros da URL

🗂️ Campos Disponíveis (fields)

💡 Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis Erros

➕ Criação de Cupom

📋 Descrição

📝 Parâmetros

🏷️ Headers Obrigatórios

📦 Parâmetros do Corpo

💡 Exemplo de Requisição

✅ Resposta de Sucesso