Skip to content

🎁 Documentação de Brindes

📋 Visão Geral

Um brinde é uma promoção que entrega produtos do catálogo ao cliente, com desconto de 100%, quando as regras definidas são atendidas.

Qualquer produto do catálogo pode ser brinde, sem cadastro separado. O produto continua à venda normalmente.

O brinde reúne cinco configurações:

  • Geral: título, situação (ativo ou inativo) e vigência.
  • Políticas comerciais: onde o brinde fica disponível.
  • Segmentação: para quais produtos e clientes o brinde vale.
  • Produtos ofertados: o que o cliente recebe e de que forma.
  • Distribuição e comportamento: quantos brindes são distribuídos e como o brinde se comporta no frete.
  • Os campos items, warnings, scheduling e segmentation são sempre retornados no detalhe. Na listagem, informe-os no parâmetro fields para carregá-los.

    🔄 Entidades Envolvidas

    Cada brinde possui uma entidade promocional própria, retornada em promotionalEntityId. A entidade guarda o título, a situação e as políticas comerciais.

    A vigência e a segmentação do brinde são gerenciadas pelos recursos compartilhados common/scheduling e common/segmentation. Nas duas rotas, informe entity como promotionalEntity e entityId com o valor de promotionalEntityId.

    A entidade de um brinde não pode ser editada pela rota promotionals/entities, e não pode ser usada em promoções ou cupons.

    ✅ Fluxo de Configuração

    1. Crie o brinde em POST /promotionals/gifts. Ele nasce inativo.

    2. Defina a vigência em POST /common/scheduling. A data inicial é obrigatória e a data final é opcional.

    3. Defina os produtos em PUT /promotionals/gifts/{giftId}/items.

    4. Defina a distribuição em PUT /promotionals/gifts/{giftId}/distribution.

    5. Opcionalmente, defina a segmentação em POST /common/segmentation.

    6. Ative o brinde em PUT /promotionals/gifts/{giftId} com active igual a true.

    A ativação exige que os produtos e a distribuição estejam configurados. Caso contrário, o endpoint retorna o erro UAPPI_STORE_GIFT_INCOMPLETE.

    🎯 Modos de Entrega

    ModoDescrição
    allTodos os produtos selecionados entram no carrinho juntos
    drawO sistema sorteia produtos entre os selecionados
    chooseO cliente escolhe produtos entre os selecionados
    Nos modos draw e choose, são obrigatórios maxItemsQuantity e allowRepeat. Sem repetição, maxItemsQuantity não pode ser maior que a quantidade de produtos selecionados.

    A contagem é por SKU. Não existe quantidade por produto.

    ⏸️ Brinde Pausado

    O campo paused indica que o brinde está pausado automaticamente. O motivo vem em pausedReason:

    MotivoDescrição
    total-reachedO limite total de brindes foi atingido
    out-of-scheduleO brinde está fora da vigência: ainda não começou ou já terminou
    A pausa é calculada na leitura. O campo active não muda e continua refletindo a escolha do usuário.

    ⚠️ Avisos

    O campo warnings é recalculado a cada leitura. Os avisos não bloqueiam o salvamento.

    TipoDescrição
    item-out-of-stockO produto selecionado está sem estoque
    item-inactiveO produto selecionado foi inativado ou removido depois de salvo
    item-without-dimensionsO produto não tem todas as dimensões cadastradas. Só aparece quando considerShippingDimensions é true
    invalid-quantitymaxItemsQuantity é maior que a quantidade de produtos, sem repetição

    🏷️ Políticas Comerciais

    O mapa tradePolicies vincula o brinde às políticas comerciais. Um brinde sem nenhuma política vinculada não fica disponível em nenhuma política comercial. Para disponibilizá-lo em todas, informe todas as políticas da loja.

    Ao atualizar o brinde, um mapa vazio ou omitido mantém os vínculos atuais.

    🔢 Prioridade

    Cada brinde tem uma priority. Quando mais de um brinde vale para o mesmo carrinho, o de menor número tem prioridade. Um brinde novo entra na última posição.

    📌 Observações

  • Os limites contam brindes, não unidades dos produtos.
  • O campo quantityDistributed informa quantos brindes já foram distribuídos.
  • Os campos totalLimit e customerLimit retornam null quando não há limite.

📋 Listagem de Brindes

GET /promotionals/gifts

Retorna a listagem paginada de brindes cadastrados na loja

📋 Descrição

Endpoint utilizado para carregar os brindes cadastrados na plataforma, com suporte a paginação, filtros, ordenação e campos opcionais.

É consumido principalmente pelo painel administrativo, na listagem de brindes. O limite máximo por página é 100 registros: um valor acima disso volta para o padrão de 10.

Por padrão, os campos items, scheduling e segmentation não são carregados e warnings retorna vazio. Informe-os no parâmetro fields quando precisar deles na listagem.

Requer o escopo GIFT_READ.

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

🗂️ Campos Disponíveis (fields)

CampoDescrição
itemsProdutos ofertados
warningsAvisos recalculados na leitura
schedulingVigência do brinde, com datas de início e fim
segmentationSegmentação e regras de elegibilidade

🔎 Campos de Condição Disponíveis

CampoTipoDescrição
idintegerID do brinde
titlestringTítulo do brinde.
activebooleanFiltra brindes ativos ou inativos
tradePolicyIdintegerID da política comercial vinculada ao brinde
createdAtstringData de criação do brinde
updatedAtstringData da última atualização do brinde

🔃 Campos de Ordenação Disponíveis

CampoDescrição
idID do brinde
titleTítulo do brinde
priorityPosição de prioridade
createdAtData de criação
updatedAtData da última atualização

💡 Exemplo de Requisição

1curl --request GET \
2 --url "{{MAIN_URL}}/promotionals/gifts?fields[]=scheduling&order[0][field]=priority&order[0][order]=asc&condition[conditions][0][field]=active&condition[conditions][0][value]=1" \
3 --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4 --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2 "status": true,
3 "data": {
4 "registers": [
5 {
6 "id": 8,
7 "promotionalEntityId": 52,
8 "title": "Brinde na compra acima de R$ 200",
9 "active": true,
10 "paused": false,
11 "pausedReason": null,
12 "deliveryMode": "all",
13 "maxItemsQuantity": null,
14 "allowRepeat": null,
15 "items": null,
16 "totalLimit": 150,
17 "customerLimit": 1,
18 "considerShippingDimensions": true,
19 "distributionConfigured": true,
20 "priority": 1,
21 "quantityDistributed": 0,
22 "scheduling": {
23 "id": 132,
24 "startDate": "2026-10-19 13:55:54",
25 "endDate": null
26 },
27 "segmentation": null,
28 "tradePolicies": [1],
29 "warnings": [],
30 "createdAt": "2026-10-20 13:51:36",
31 "updatedAt": "2026-10-20 13:51:36"
32 }
33 ],
34 "pagination": {
35 "limit": 10,
36 "offset": 0,
37 "pages": 1,
38 "registers": 1
39 }
40 }
41}

📋 Listagem Completa de Brindes

GET /promotionals/gifts/all

Retorna o título de todos os brindes da loja, indexado pelo ID

📋 Descrição

Endpoint utilizado para carregar o título de todos os brindes cadastrados de uma vez, sem paginação. A resposta é um objeto em que a chave é o ID do brinde e o valor é o seu título.

Serve para preencher listas de seleção. Para os demais dados do brinde, como status, prioridade e vigência, use a listagem paginada (GET /promotionals/gifts) ou o detalhe do brinde.

Requer o escopo GIFT_READ.

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação
Este endpoint não recebe parâmetros de busca.

💡 Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

A resposta é um objeto com o título de cada brinde, indexado pelo ID.

1{
2 "status": true,
3 "data": {
4 "8": "Brinde na compra acima de R$ 200",
5 "12": "Meia de brinde na compra de tênis"
6 }
7}

⚠️ 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 InternoHTTPDescrição
UAPPI_AUTH_USER_NOT_FOUND401❌ O token informado não pertence a um usuário válido.

🔍 Detalhe de Brinde

GET /promotionals/gifts/{giftId}

Retorna os detalhes de um brinde com produtos, vigência, segmentação e avisos

📋 Descrição

Endpoint responsável por retornar um brinde identificado pelo giftId na URL.

O detalhe sempre inclui os campos items, warnings, scheduling e segmentation. O parâmetro fields é aceito para carregar campos extras.

Os warnings são recalculados a cada leitura. Eles refletem o estado atual dos produtos, como estoque e dimensões.

Caso o brinde não seja encontrado, o endpoint retorna erro 404 com o código UAPPI_STORE_GIFT_NOT_FOUND.

Requer o escopo GIFT_READ.

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

🔑 Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
giftIdinteger✅ SimID do brinde

💡 Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

Cada item de items traz os dados completos do produto. O exemplo mostra apenas os principais campos.

1{
2 "status": true,
3 "data": {
4 "id": 8,
5 "promotionalEntityId": 52,
6 "title": "Brinde na compra acima de R$ 200",
7 "active": true,
8 "paused": false,
9 "pausedReason": null,
10 "deliveryMode": "draw",
11 "maxItemsQuantity": 2,
12 "allowRepeat": false,
13 "items": [
14 {
15 "productId": 42,
16 "type": "product",
17 "sku": "TRQ HMD",
18 "name": "Traqueia 22mm - Nacional",
19 "active": true,
20 "stock": 5
21 },
22 {
23 "productId": 159,
24 "type": "product",
25 "sku": "MN BMC IN4",
26 "name": "Máscara Nasal Ivolve N4 BMC",
27 "active": true,
28 "stock": 20
29 }
30 ],
31 "totalLimit": 100,
32 "customerLimit": 5,
33 "considerShippingDimensions": true,
34 "distributionConfigured": true,
35 "priority": 1,
36 "quantityDistributed": 0,
37 "scheduling": {
38 "id": 132,
39 "startDate": "2026-10-19 13:55:54",
40 "endDate": null
41 },
42 "segmentation": {
43 "id": 64,
44 "operator": "and",
45 "sellerId": null,
46 "userForAllSellers": false,
47 "rules": [
48 {
49 "id": 189,
50 "ruleType": "total-products-value",
51 "ruleOperator": "greater-or-equal",
52 "ruleValue": 200
53 }
54 ]
55 },
56 "tradePolicies": [1],
57 "warnings": [
58 {
59 "type": "item-without-dimensions",
60 "productId": 159
61 }
62 ],
63 "createdAt": "2026-10-20 13:51:36",
64 "updatedAt": "2026-10-20 14:02:11"
65 }
66}

⚠️ 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 InternoHTTPDescrição
UAPPI_STORE_GIFT_NOT_FOUND404❌ O brinde solicitado não foi encontrado.

➕ Criação de Brinde

POST /promotionals/gifts

Permite criar um novo brinde na loja

📋 Descrição

Endpoint responsável por criar um novo brinde. A entidade promocional do brinde é criada junto, e o promotionalEntityId é retornado na resposta.

O brinde nasce sem produtos e sem distribuição configurados, e entra na última posição de prioridade. Por isso, ele não pode ser criado ativo: enviar active igual a true retorna o erro UAPPI_STORE_GIFT_INCOMPLETE.

O título pode se repetir entre brindes.

A vigência e a segmentação são definidas depois, pelos recursos common/scheduling e common/segmentation, usando o promotionalEntityId retornado.

Requer os escopos GIFT_READ e GIFT_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

📦 Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
titlestring✅ SimTítulo do brinde. Até 255 caracteres
activeboolean✅ SimSituação do brinde. Na criação, só aceita false na prática
tradePoliciesobject❌ NãoMapa de ID da política comercial para booleano. Sem nenhuma política, o brinde não fica disponível em nenhuma

💡 Exemplo de Requisição

1curl --request POST \
2 --url {{MAIN_URL}}/promotionals/gifts \
3 --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4 --header "Content-Type: application/json" \
5 --data '{
6 "title": "Brinde na compra acima de R$ 200",
7 "active": false,
8 "tradePolicies": { "1": true }
9 }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2 "status": true,
3 "data": {
4 "id": 8,
5 "promotionalEntityId": 52,
6 "title": "Brinde na compra acima de R$ 200",
7 "active": false,
8 "paused": false,
9 "pausedReason": null,
10 "deliveryMode": null,
11 "maxItemsQuantity": null,
12 "allowRepeat": null,
13 "items": [],
14 "totalLimit": null,
15 "customerLimit": null,
16 "considerShippingDimensions": true,
17 "distributionConfigured": false,
18 "priority": 1,
19 "quantityDistributed": 0,
20 "scheduling": null,
21 "segmentation": null,
22 "tradePolicies": [1],
23 "warnings": [],
24 "createdAt": "2026-10-20 13:51:36",
25 "updatedAt": "2026-10-20 13:51:36"
26 }
27}

⚠️ 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 InternoHTTPDescrição
UAPPI_STORE_GIFT_INCOMPLETE400❌ O brinde não pode ser ativado porque os produtos ou a distribuição não estão configurados.

✏️ Atualização de Brinde

PUT /promotionals/gifts/{giftId}

Atualiza o título, a situação e as políticas comerciais de um brinde

📋 Descrição

Endpoint responsável por atualizar o título, a situação e as políticas comerciais de um brinde identificado pelo giftId na URL.

Também é usado para ativar ou desativar o brinde, com o campo active.

Para ativar o brinde, os produtos ofertados e a distribuição precisam estar configurados. Caso contrário, o endpoint retorna erro 400 com o código UAPPI_STORE_GIFT_INCOMPLETE. Desativar é sempre permitido.

O mapa tradePolicies substitui os vínculos informados. Um mapa vazio ou omitido mantém os vínculos atuais.

Para alterar produtos, distribuição, vigência ou segmentação, utilize os endpoints próprios.

Requer os escopos GIFT_READ e GIFT_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

🔑 Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
giftIdinteger✅ SimID do brinde a ser atualizado

📦 Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
titlestring✅ SimTítulo do brinde. Até 255 caracteres
activeboolean✅ SimSituação do brinde. true exige produtos e distribuição configurados
tradePoliciesobject❌ NãoMapa de ID da política comercial para booleano

💡 Exemplo de Requisição

1curl --request PUT \
2 --url {{MAIN_URL}}/promotionals/gifts/8 \
3 --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4 --header "Content-Type: application/json" \
5 --data '{
6 "title": "Brinde na compra acima de R$ 200",
7 "active": true,
8 "tradePolicies": { "1": true }
9 }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

A resposta tem o mesmo formato do Detalhe de Brinde.

1{
2 "status": true,
3 "data": {
4 "id": 8,
5 "promotionalEntityId": 52,
6 "title": "Brinde na compra acima de R$ 200",
7 "active": true,
8 "paused": false,
9 "pausedReason": null,
10 "deliveryMode": "all",
11 "priority": 1,
12 "quantityDistributed": 0,
13 "tradePolicies": [1],
14 "warnings": []
15 }
16}

O exemplo mostra apenas os principais campos.

⚠️ 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 InternoHTTPDescrição
UAPPI_STORE_GIFT_NOT_FOUND404❌ O brinde solicitado não foi encontrado.
UAPPI_STORE_GIFT_INCOMPLETE400❌ O brinde não pode ser ativado porque os produtos ou a distribuição não estão configurados.

🛍️ Atualização dos Produtos Ofertados

PUT /promotionals/gifts/{giftId}/items

Define os produtos ofertados por um brinde e como o cliente os recebe

📋 Descrição

Endpoint responsável por definir os produtos ofertados por um brinde e o modo de entrega ao cliente.

A lista de produtos é sempre enviada por completo e substitui a lista atual. Para trocar ou remover um produto, envie a nova lista completa. O salvamento é atômico: ou tudo é salvo, ou nada é.

Os produtos são SKUs. Não existe quantidade por produto.

Nos modos draw e choose, os campos maxItemsQuantity e allowRepeat são obrigatórios. No modo all, eles são ignorados e gravados como null.

Sem repetição (allowRepeat igual a false), maxItemsQuantity não pode ser maior que a quantidade de produtos enviados. Com repetição, pode ser.

Um produto inativo, um produto inexistente e um produto-pai que possui variações são recusados.

Requer os escopos GIFT_READ e GIFT_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

🔑 Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
giftIdinteger✅ SimID do brinde

📦 Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
deliveryModestring✅ SimModo de entrega. Valores: all, draw, choose
maxItemsQuantityintegerCondicionalMáximo de produtos entregues por brinde. Obrigatório em draw e choose. Mínimo 1
allowRepeatbooleanCondicionalDefine se o mesmo produto pode ser entregue mais de uma vez. Obrigatório em draw e choose
productIdsarray de integer✅ SimIDs dos produtos (SKUs). Pelo menos um, sem repetir o mesmo ID

💡 Exemplo de Requisição

1curl --request PUT \
2 --url {{MAIN_URL}}/promotionals/gifts/8/items \
3 --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4 --header "Content-Type: application/json" \
5 --data '{
6 "deliveryMode": "draw",
7 "maxItemsQuantity": 2,
8 "allowRepeat": false,
9 "productIds": [42, 47, 61]
10 }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

A resposta tem o mesmo formato do Detalhe de Brinde, com os produtos e os avisos já recalculados.

1{
2 "status": true,
3 "data": {
4 "id": 8,
5 "deliveryMode": "draw",
6 "maxItemsQuantity": 2,
7 "allowRepeat": false,
8 "items": [
9 { "productId": 42, "sku": "TRQ HMD", "active": true, "stock": 5 },
10 { "productId": 47, "sku": "FIL CP PH RE", "active": true, "stock": 14 },
11 { "productId": 61, "sku": "RES AGU RESM", "active": true, "stock": 20 }
12 ],
13 "warnings": []
14 }
15}

O exemplo mostra apenas os principais campos.

⚠️ 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 InternoHTTPDescrição
UAPPI_STORE_GIFT_NOT_FOUND404❌ O brinde solicitado não foi encontrado.
UAPPI_STORE_GIFT_ITEM_NOT_FOUND404❌ Um dos produtos informados não foi encontrado.
UAPPI_STORE_GIFT_ITEM_INACTIVE400❌ Um dos produtos informados está inativo.
UAPPI_STORE_GIFT_ITEM_IS_PARENT400❌ Um dos produtos informados possui variações. Selecione uma das variações.
UAPPI_STORE_GIFT_ITEMS_QUANTITY_EXCEEDS_ITEMS400❌ maxItemsQuantity é maior que a quantidade de produtos e a repetição não é permitida.

📦 Atualização da Distribuição e do Comportamento

PUT /promotionals/gifts/{giftId}/distribution

Define os limites de distribuição e o comportamento de um brinde

📋 Descrição

Endpoint responsável por definir os limites de distribuição e o comportamento de um brinde.

Todos os campos são enviados em toda chamada. Os dois limites exigem o campo presente: envie null para indicar sem limite, ou um número maior que zero.

Os limites contam brindes, não unidades dos produtos.

O limite por cliente não pode ser maior que o limite total. A validação ignora o limite que estiver como null.

Reduzir o limite total para um valor menor que a quantidade já distribuída é permitido. Nesse caso, o brinde passa a retornar paused igual a true, com o motivo total-reached.

Depois de salvar, o campo distributionConfigured passa a ser true, mesmo quando os dois limites são null (sem limite). Use esse campo, e não os limites, para saber se o bloco já foi salvo.

Com considerShippingDimensions ativo, as dimensões do brinde entram no cálculo de frete. Os produtos sem dimensões cadastradas retornam o aviso item-without-dimensions no detalhe.

Requer os escopos GIFT_READ e GIFT_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

🔑 Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
giftIdinteger✅ SimID do brinde

📦 Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
totalLimitinteger ou null✅ SimLimite total de brindes distribuídos. null indica sem limite
customerLimitinteger ou null✅ SimLimite de brindes por cliente. null indica sem limite
considerShippingDimensionsboolean✅ SimDefine se as dimensões do brinde entram no cálculo de frete

💡 Exemplo de Requisição

1curl --request PUT \
2 --url {{MAIN_URL}}/promotionals/gifts/8/distribution \
3 --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4 --header "Content-Type: application/json" \
5 --data '{
6 "totalLimit": 100,
7 "customerLimit": 5,
8 "considerShippingDimensions": true
9 }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

A resposta tem o mesmo formato do Detalhe de Brinde.

1{
2 "status": true,
3 "data": {
4 "id": 8,
5 "totalLimit": 100,
6 "customerLimit": 5,
7 "considerShippingDimensions": true,
8 "distributionConfigured": true,
9 "paused": false,
10 "warnings": [
11 { "type": "item-without-dimensions", "productId": 159 }
12 ]
13 }
14}

O exemplo mostra apenas os principais campos.

⚠️ 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 InternoHTTPDescrição
UAPPI_STORE_GIFT_NOT_FOUND404❌ O brinde solicitado não foi encontrado.
UAPPI_STORE_GIFT_CUSTOMER_LIMIT_EXCEEDS_TOTAL400❌ O limite por cliente é maior que o limite total.

🔢 Atualização da Prioridade dos Brindes

PUT /promotionals/gifts/order

Define a prioridade entre os brindes

📋 Descrição

Endpoint responsável por definir a prioridade entre os brindes. Quando mais de um brinde vale para o mesmo carrinho, o de menor número tem prioridade.

Cada brinde e cada posição podem aparecer uma única vez na lista. Posições repetidas retornam erro de validação.

O salvamento é atômico: se algum brinde da lista não existir, nenhuma posição é gravada.

A lista deve conter todos os brindes, cada um uma vez, com as posições de 1 até o total de brindes, sem repetição. Se faltar brinde ou posição, o endpoint retorna erro 400 com o código UAPPI_STORE_GIFT_ORDER_INCOMPLETE e nada é gravado. Para obter todos os brindes, percorra as páginas da listagem (GET /promotionals/gifts).

Na resposta, o campo data retorna true.

Requer os escopos GIFT_READ e GIFT_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

📦 Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
giftsarray✅ SimLista com todos os brindes e a nova posição de cada um
gifts.*.giftIdinteger✅ SimID do brinde. Não pode se repetir na lista
gifts.*.orderinteger✅ SimPosição de prioridade, a partir de 1. Não pode se repetir na lista

💡 Exemplo de Requisição

1curl --request PUT \
2 --url {{MAIN_URL}}/promotionals/gifts/order \
3 --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4 --header "Content-Type: application/json" \
5 --data '{
6 "gifts": [
7 { "giftId": 2, "order": 1 },
8 { "giftId": 8, "order": 2 }
9 ]
10 }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

⚠️ 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 InternoHTTPDescrição
UAPPI_STORE_GIFT_NOT_FOUND404❌ Um dos brindes informados não foi encontrado. Nenhuma posição é gravada.
UAPPI_STORE_GIFT_ORDER_INCOMPLETE400❌ A lista não contém todos os brindes, ou as posições não vão de 1 até o total de brindes. Nenhuma posição é gravada.

🗑️ Exclusão de Brinde

DELETE /promotionals/gifts/{giftId}

Remove permanentemente um brinde da plataforma

📋 Descrição

Endpoint responsável por remover permanentemente um brinde, identificado pelo giftId na URL.

A exclusão remove também os vínculos com os produtos ofertados, a vigência, a segmentação e a entidade promocional do brinde. Os produtos continuam no catálogo. A operação é atômica.

Caso o brinde não seja encontrado, o endpoint retorna erro 404 com o código UAPPI_STORE_GIFT_NOT_FOUND.

Quando a exclusão é realizada com sucesso, o campo data retorna true.

Requer os escopos GIFT_READ e GIFT_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

🔑 Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
giftIdinteger✅ SimID do brinde a ser removido

💡 Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

⚠️ 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 InternoHTTPDescrição
UAPPI_STORE_GIFT_NOT_FOUND404❌ O brinde solicitado não foi encontrado.

Uappi é a melhor opção para o crescimento da sua loja!

;