🎁 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 limites contam brindes, não unidades dos produtos.
- O campo
quantityDistributedinforma quantos brindes já foram distribuídos. - Os campos
totalLimitecustomerLimitretornamnullquando não há limite.
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
| Modo | Descrição |
|---|---|
all | Todos os produtos selecionados entram no carrinho juntos |
draw | O sistema sorteia produtos entre os selecionados |
choose | O cliente escolhe produtos entre os selecionados |
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:
| Motivo | Descrição |
|---|---|
total-reached | O limite total de brindes foi atingido |
out-of-schedule | O brinde está fora da vigência: ainda não começou ou já terminou |
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.
| Tipo | Descrição |
|---|---|
item-out-of-stock | O produto selecionado está sem estoque |
item-inactive | O produto selecionado foi inativado ou removido depois de salvo |
item-without-dimensions | O produto não tem todas as dimensões cadastradas. Só aparece quando considerShippingDimensions é true |
invalid-quantity | maxItemsQuantity é 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
📋 Listagem de Brindes
/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
| 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 |
|---|---|
| items | Produtos ofertados |
| warnings | Avisos recalculados na leitura |
| scheduling | Vigência do brinde, com datas de início e fim |
| segmentation | Segmentação e regras de elegibilidade |
🔎 Campos de Condição Disponíveis
| Campo | Tipo | Descrição |
|---|---|---|
| id | integer | ID do brinde |
| title | string | Título do brinde. |
| active | boolean | Filtra brindes ativos ou inativos |
| tradePolicyId | integer | ID da política comercial vinculada ao brinde |
| createdAt | string | Data de criação do brinde |
| updatedAt | string | Data da última atualização do brinde |
🔃 Campos de Ordenação Disponíveis
| Campo | Descrição |
|---|---|
| id | ID do brinde |
| title | Título do brinde |
| priority | Posição de prioridade |
| createdAt | Data de criação |
| updatedAt | Data 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": null26 },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": 139 }40 }41}📋 Listagem Completa de Brindes
/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
| Header | Valor | Descrição |
|---|---|---|
| Content-Type | application/json | Tipo de conteúdo |
| Authorization | Bearer SEU_TOKEN_AQUI | Token de autenticação |
💡 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 Interno | HTTP | Descrição |
|---|---|---|
| UAPPI_AUTH_USER_NOT_FOUND | 401 | ❌ O token informado não pertence a um usuário válido. |
🔍 Detalhe de Brinde
/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
| 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 |
|---|---|---|---|
| giftId | integer | ✅ Sim | ID 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": 521 },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": 2029 }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": null41 },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": 20053 }54 ]55 },56 "tradePolicies": [1],57 "warnings": [58 {59 "type": "item-without-dimensions",60 "productId": 15961 }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 Interno | HTTP | Descrição |
|---|---|---|
| UAPPI_STORE_GIFT_NOT_FOUND | 404 | ❌ O brinde solicitado não foi encontrado. |
➕ Criação de Brinde
/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
| 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 |
|---|---|---|---|
| title | string | ✅ Sim | Título do brinde. Até 255 caracteres |
| active | boolean | ✅ Sim | Situação do brinde. Na criação, só aceita false na prática |
| tradePolicies | object | ❌ Não | Mapa 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 Interno | HTTP | Descrição |
|---|---|---|
| UAPPI_STORE_GIFT_INCOMPLETE | 400 | ❌ O brinde não pode ser ativado porque os produtos ou a distribuição não estão configurados. |
✏️ Atualização de Brinde
/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
| 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 |
|---|---|---|---|
| giftId | integer | ✅ Sim | ID do brinde a ser atualizado |
📦 Parâmetros do Corpo
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| title | string | ✅ Sim | Título do brinde. Até 255 caracteres |
| active | boolean | ✅ Sim | Situação do brinde. true exige produtos e distribuição configurados |
| tradePolicies | object | ❌ Não | Mapa 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 Interno | HTTP | Descrição |
|---|---|---|
| UAPPI_STORE_GIFT_NOT_FOUND | 404 | ❌ O brinde solicitado não foi encontrado. |
| UAPPI_STORE_GIFT_INCOMPLETE | 400 | ❌ O brinde não pode ser ativado porque os produtos ou a distribuição não estão configurados. |
🛍️ Atualização dos Produtos Ofertados
/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
| 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 |
|---|---|---|---|
| giftId | integer | ✅ Sim | ID do brinde |
📦 Parâmetros do Corpo
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| deliveryMode | string | ✅ Sim | Modo de entrega. Valores: all, draw, choose |
| maxItemsQuantity | integer | Condicional | Máximo de produtos entregues por brinde. Obrigatório em draw e choose. Mínimo 1 |
| allowRepeat | boolean | Condicional | Define se o mesmo produto pode ser entregue mais de uma vez. Obrigatório em draw e choose |
| productIds | array de integer | ✅ Sim | IDs 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 Interno | HTTP | Descrição |
|---|---|---|
| UAPPI_STORE_GIFT_NOT_FOUND | 404 | ❌ O brinde solicitado não foi encontrado. |
| UAPPI_STORE_GIFT_ITEM_NOT_FOUND | 404 | ❌ Um dos produtos informados não foi encontrado. |
| UAPPI_STORE_GIFT_ITEM_INACTIVE | 400 | ❌ Um dos produtos informados está inativo. |
| UAPPI_STORE_GIFT_ITEM_IS_PARENT | 400 | ❌ Um dos produtos informados possui variações. Selecione uma das variações. |
| UAPPI_STORE_GIFT_ITEMS_QUANTITY_EXCEEDS_ITEMS | 400 | ❌ maxItemsQuantity é maior que a quantidade de produtos e a repetição não é permitida. |
📦 Atualização da Distribuição e do Comportamento
/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
| 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 |
|---|---|---|---|
| giftId | integer | ✅ Sim | ID do brinde |
📦 Parâmetros do Corpo
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| totalLimit | integer ou null | ✅ Sim | Limite total de brindes distribuídos. null indica sem limite |
| customerLimit | integer ou null | ✅ Sim | Limite de brindes por cliente. null indica sem limite |
| considerShippingDimensions | boolean | ✅ Sim | Define 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": true9 }'✅ 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 Interno | HTTP | Descrição |
|---|---|---|
| UAPPI_STORE_GIFT_NOT_FOUND | 404 | ❌ O brinde solicitado não foi encontrado. |
| UAPPI_STORE_GIFT_CUSTOMER_LIMIT_EXCEEDS_TOTAL | 400 | ❌ O limite por cliente é maior que o limite total. |
🔢 Atualização da Prioridade dos Brindes
/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
| 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 |
|---|---|---|---|
| gifts | array | ✅ Sim | Lista com todos os brindes e a nova posição de cada um |
| gifts.*.giftId | integer | ✅ Sim | ID do brinde. Não pode se repetir na lista |
| gifts.*.order | integer | ✅ Sim | Posiçã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": true4}⚠️ 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_STORE_GIFT_NOT_FOUND | 404 | ❌ Um dos brindes informados não foi encontrado. Nenhuma posição é gravada. |
| UAPPI_STORE_GIFT_ORDER_INCOMPLETE | 400 | ❌ 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
/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
| 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 |
|---|---|---|---|
| giftId | integer | ✅ Sim | ID 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": true4}⚠️ 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_STORE_GIFT_NOT_FOUND | 404 | ❌ O brinde solicitado não foi encontrado. |