Skip to content

Busca de segmentação

GET /common/segmentation/{segmentationId}

Busca de segmentação

Descrição

Este endpoint é responsável por retornar uma segmentação específica, identificada pelo seu ID, previamente cadastrada na API. A requisição permite recuperar todas as informações associadas à segmentação informada, incluindo a entidade segmentada, o operador lógico definido e as regras configuradas no momento do cadastro ou da última atualização.

Opcionalmente, é possível solicitar o mapa de entidades (entityMap) através do campo fields. Quando solicitado, a resposta inclui os nomes legíveis dos IDs referenciados nas regras, agrupados por tipo de regra.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
segmentationIdinteger✅ID único da segmentação a ser buscada

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
fieldsarray❌Campos adicionais a serem retornados. Valores aceitos: entityMap

Exemplo de Requisição

1curl --request GET \
2  --url https://sua-loja-uappi.com.br/api/v3/common/segmentation/{segmentationId} \
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "fields": ["entityMap"]
6  }'

✅ Resposta de Sucesso

1{
2  "id": 1,
3  "operator": "and",
4  "sellerId": null,
5  "userForAllSellers": false,
6  "rules": [
7    {
8      "id": 1,
9      "ruleType": "category-id",
10      "ruleOperator": "in",
11      "ruleValue": [1, 2, 3],
12      "entityMap": {
13        "1": "Eletrônicos",
14        "2": "Informática",
15        "3": "Celulares"
16      },
17      "createdAt": "2024-08-21 00:00:00",
18      "updatedAt": "2025-09-01 13:11:44"
19    },
20    {
21      "id": 2,
22      "ruleType": "customer-age",
23      "ruleOperator": "between",
24      "ruleValue": [18, 35],
25      "createdAt": "2026-04-16 00:00:00",
26      "updatedAt": "2026-04-16 00:00:00"
27    }
28  ]
29}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

1{
2  "status": false,
3  "data": {
4    "code": 404,
5    "errorCode": "UAPPI_STORE_SEGMENTATION_NOT_FOUND",
6    "message": "The requested segmentation was not found."
7  }
8}

Cadastro e atualização de segmentação

POST /common/segmentation

Cadastro e atualização de segmentação

Descrição

Segmentação

Este endpoint é responsável por cadastrar e atualizar segmentações, permitindo definir regras específicas com base em diferentes tipos de entidades.

O tipo de entidade a ser segmentada deve ser informado como promotionalEntity, upsell ou pointSystemRule.

Após essa definição, é necessário informar o identificador correspondente da entidade e o operador lógico da segmentação, que pode ser and ou or.

Essa escolha define como as regras serão combinadas na validação ⚙️

---

Regras da segmentação

Com a entidade definida, as regras da segmentação devem ser configuradas a partir do tipo de regra.

Os tipos disponíveis são: product-id, category-id, customer-id, total-quantity, total-value, zip-code e customer-age.

Em seguida, deve ser definido o operador da regra, responsável por determinar a condição que será validada.

Os operadores disponíveis permitem diferentes tipos de comparação, como igualdade, diferença, intervalo ou inclusão/exclusão de valores. Entre eles:

less, equal, greater, in, not-in, contains e between.

Após definir o operador, devem ser informados os identificadores ou valores que serão utilizados na validação da condição 🎯

---

Operador lógico da entidade

Quando o operador lógico da entidade for definido como and, será necessário adicionar um novo bloco de regras no corpo da requisição.

Isso garante que todas as condições configuradas sejam atendidas simultaneamente.

Já ao utilizar or, basta que uma das condições seja satisfeita para que a segmentação seja aplicada.

---

Atualização de segmentação

Além do cadastro, este endpoint também pode ser utilizado para atualizar uma segmentação existente.

Para isso, é necessário informar o campo id no corpo da requisição.

Com essa informação, o sistema entenderá automaticamente que a ação corresponde a uma atualização.

No entanto, é importante observar que a atualização envolve apenas a segmentação.

As regras não são alteradas parcialmente.

Qualquer regra informada será recriada integralmente com base nas novas definições enviadas na requisição 🔄

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {token}Token de autenticação

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
idinteger❌id da segmentação a ser atualizada (específico para atualização)
entitystring✅tipo da entidade que a segmentação vai pertencer (promotionalEntity, upsell, pointSystem)
entityIdinteger✅id da entidade a ser associada
operatorstring✅Tipo de operador "AND" ou "OR" que determina se deve ser respeitada todas as regras ou pelo menos 1 para ativar a segmentação
userForAllSellersboolean✅Se deve ser aplicado para todos os sellers
rulesarrayObrigatório em cenários de cadastroLista de regras que devem ser criadas com a segmentação.
rules.*.ruleTypestring✅Determina o tipo da regra (product-id, category-id, customer-id, total-quantity, total-value, zip-code, customer-age)
rules.*.ruleOperatorstring✅Operador lógico da regra (less, equal, greater, in, not-in, contains, between)
rules.*.rulevalueinteger - decimal - string✅Valor que a regra deve conter (contém mais de uma tipagem)

Exemplo de Requisição - Cadastro

1curl --request POST \
2  --url {{MAIN_URL}}/common/segmentation \
3  --header "Authorization: Bearer  userToken" \
4  --data '{
5    "entity": "upsell",
6    "entityId": 1,
7    "operator": "and",
8    "userForAllSellers": false,
9    "rules":[
10      {
11        "ruleType":"product-id",
12        "ruleOperator":"in",
13        "ruleValue":[1,2,3,4,5]
14      }
15    ]
16  }'

Exemplo de Requisição - Atualização

1curl --request POST \
2  --url {{MAIN_URL}}/common/segmentation \
3  --header "Authorization: Bearer  userToken" \
4  --data '{
5    "id": 1,
6    "entity": "upsell",
7    "entityId": 1,
8    "operator": "or",
9    "userForAllSellers": false,
10    "rules":[]
11  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 1,
3  "operator": "and",
4  "sellerId": null,
5  "userForAllSellers": false,
6  "rules": [
7    {
8      "id": 1,
9      "ruleType": "category-id",
10      "ruleOperator": "in",
11      "ruleValue": [
12        1,
13        2,
14        3,
15        4,
16        5
17      ],
18      "entityMap": {
19        "1": "Eletrônicos",
20        "2": "Informática",
21        "3": "Celulares",
22        "4": "Games",
23        "5": "Áudio"
24      },
25      "createdAt": "2026-02-05 19:19:31",
26      "updatedAt": "2026-02-05 19:19:31",
27    }
28  ]
29}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código InternoCódigo HttpDescrição
UAPPI_STORE_SEGMENTATION_NOT_FOUND404A segmentação solicitada não foi encontrada.
UAPPI_STORE_PROMOTIONAL_ENTITY_NOT_FOUND404A entidade promocional solicitada não foi encontrada.
UAPPI_STORE_UPSELL_NOT_FOUND404O upsell solicitado não foi encontrado.
UAPPI_STORE_POINT_SYSTEM_RULE_NOT_FOUND404Os pontos solicitados não foram encontrados.

Execução de segmentação

POST /common/segmentation/{segmentationId}/run

Executar segmentação

Descrição

Este endpoint é responsável por executar uma segmentação previamente cadastrada e retornar todas as informações relacionadas ao seu processamento.

Consiste em uma simulação da segmentação em contexto real, para que o lojista consiga testar o fluxo e atendimento das regras da segmentação estão ocorrendo corretamente.

No corpo da requisição são enviados os parâmetros de referência utilizados para testar a segmentação (como productId, categoryId, brandId, quantity entre outros). Esses mesmos parâmetros são retornados na resposta, garantindo rastreabilidade da execução.

Também são informadas as regras que foram atendidas e eventuais erros identificados durante o processamento ⚙️

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {userToken}Token de autenticação

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
segmentationIdintegerSimID único da segmentação a ser executada

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
itemsarray✅Array de itens de segmentação
items.*.productIdinteger❌id do produto
items.*.categoryIdsarray❌ids das categorias
items.*.brandIdinteger❌id da marca
items.*.tradePolicyIdinteger❌política comercial
items.*.customerIdinteger❌id do cliente
items.*.zipCodestring❌CEP para comparação
items.*.customerAgeinteger❌Idade do cliente
items.*.quantityinteger❌quantidade de itens
items.*.valuedecimal❌valor do item

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/common/segmentation/{segmentationId}/run\
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "items": [
6      "productId": 1,
7      "categoryIds": [1],
8      "brandId": 1,
9      "tradePolicyId": 1,
10      "customerId": 1,
11      "zipCode": "04726010",
12      "customerAge": 18,
13      "quantity": 3,
14      "value": 300
15    ]
16  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "success": false,
6    "operator": "and",
7    "successfulItems": [],
8    "failedItems": [
9      {
10        "item": {
11          "productId": 1,
12          "categoryIds": [1],
13          "brandId": 1,
14          "tradePolicyId": 1,
15          "customerId": 1,
16          "zipCode": "04726010",
17          "customerAge": 18,
18          "quantity": 3,
19          "value": 300,
20          "externalReference": null
21        },
22        "successfulRules": [],
23        "failedRules": [
24          {
25            "id": 1,
26            "ruleType": "category-id",
27            "ruleOperator": "in",
28            "ruleValue": [
29              3,
30              8,
31              5,
32              6,
33              7,
34              2,
35              4,
36              1
37            ],
38            "createdAt": "2024-08-21 00:00:00",
39            "updatedAt": "2025-09-01 13:11:44"
40          },
41          {
42            "id": 2,
43            "ruleType": "product-id",
44            "ruleOperator": "equal",
45            "ruleValue": 90,
46            "createdAt": "2026-02-04 16:57:27",
47            "updatedAt": "2026-02-04 16:57:27"
48          },
49          {
50            "id": 3,
51            "ruleType": "category-id",
52            "ruleOperator": "equal",
53            "ruleValue": 80,
54            "createdAt": "2026-02-04 16:57:27",
55            "updatedAt": "2026-02-04 16:57:27"
56          },
57          {
58            "id": 3,
59            "ruleType": "brand-id",
60            "ruleOperator": "equal",
61            "ruleValue": 70,
62            "createdAt": "2026-02-04 16:57:27",
63            "updatedAt": "2026-02-04 16:57:27"
64          }
65        ]
66      }
67    ]
68  }
69}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

1{
2  "status": false,
3  "data": {
4    "code": 404,
5    "errorCode": "UAPPI_STORE_SEGMENTATION_NOT_FOUND",
6    "message": "The requested segmentation was not found."
7  }
8}

Excluir segmentação

DELETE /common/segmentation/{segmentationId}

Rota para excluir uma segmentação.

Descrição

Este endpoint é responsável por excluir uma segmentação previamente criada. Ao realizar a exclusão, a segmentação identificada pelo seu ID será removida da plataforma, tornando-se indisponível para consultas ou atualizações futuras.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
segmentationIdintegerSimID único da segmentação a ser excluída

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/common/segmentation/{segmentationId}\
3  --header "Authorization: Bearer userToken" \

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

1{
2  "status": false,
3  "data": {
4    "code": 404,
5    "errorCode": "UAPPI_STORE_SEGMENTATION_NOT_FOUND",
6    "message": "The requested segmentation was not found."
7  }
8}

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

Institucional

;