Documentação de Url

Visão Geral

A URL define o endereço de acesso às entidades da loja 🌐.

Ela é responsável por permitir que produtos, categorias, páginas e marcas sejam acessados de forma organizada e amigável, impactando diretamente na navegação e SEO.

Cada URL é vinculada a uma política comercial, permitindo que uma mesma entidade possua diferentes endereços conforme o contexto.

Além disso, o sistema também permite configurar redirecionamentos (redirects), garantindo que alterações de URLs não prejudiquem o acesso ou indexação.

Entidades Envolvidas

• URL (Url)
Representa o caminho de acesso da entidade (ex.: /produto-exemplo).
• Produto (Product)
• Categoria (Category)
• Marca (Brand)
• Página (Page)
Entidades que podem possuir URLs associadas.
• Política Comercial (Trade Policy)
Define o contexto em que a URL será aplicada.

Notas e Considerações

• Cada entidade pode possuir uma URL por política comercial.
• URLs devem ser únicas dentro do contexto definido.
• É possível configurar redirects (301 e 302) para manter a consistência dos acessos.
• Alterações de URL podem impactar SEO e indexação, devendo ser feitas com cuidado ⚠️.

Listagem de urls

Descrição

Endpoint responsável por retornar a lista de todas as URLs cadastradas na loja 🔗.

Atua em contexto administrativo, permitindo que o lojista visualize os endereços configurados na plataforma.

Por meio desse endpoint, é possível consultar a relação completa de URLs disponíveis, facilitando a identificação das páginas existentes no ambiente.

Dessa forma, o lojista consegue analisar quais URLs estão ativas e organizadas na loja, auxiliando na gestão de navegação, SEO e estrutura do catálogo ⚙️.

Parâmetros

Headers Obrigatórios

Campos de Condição Disponíveis

Campos de Ordenação Disponíveis

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/products/urls \
3  --header "Authorization: Bearer userToken" \

✅ Resposta de Sucesso

1{
2  "tradePolicyId": 1,
3  "url": "/tech-brand-product",
4  "entity": {
5    "productId": 1,
6    "brandId": null,
7    "brandName": null,
8    "mainCategoryId": 1,
9    "mainCategoryName": "technology",
10    "type": "product",
11    "sku": "SKU123321",
12    "name": "technology",
13    "active": false,
14    "url": "/tech-brand-tecnology",
15    "comparisonPrice": 100,
16    "stock": 1,
17    "medias": [],
18  "combination": [],
19  "currentAttributes": []
20  },
21  "active": true,
22  "redirect": false,
23  "redirectCode": null,
24  "target": null,
25  "createdAt": "2025-09-19 11:50:46",
26  "updatedAt": "2025-10-22 11:59:37",
27  "productId": 1,
28  "productCategoryId": null,
29  "productBrandId": null,
30  "productPageId": null
31}

Cadastro de url

Descrição

Endpoint responsável por criar URLs para entidades da loja 🔗.

Atua em contexto administrativo, permitindo definir o endereço de acesso de diferentes entidades na plataforma, como:

• Produtos
• Páginas
• Categorias
• Marcas

Por meio desse endpoint, é possível configurar URLs por política comercial, permitindo que uma mesma entidade possua endereços distintos conforme o contexto aplicado.

⚠️ Importante: para que a criação seja permitida, a entidade não pode possuir uma URL já cadastrada.

Caso já exista uma URL vinculada, será necessário realizar uma atualização em vez de criar uma nova.

Essa URL será utilizada como endereço de acesso na loja, sendo fundamental para navegação, SEO e identificação única da entidade.

Dessa forma, o lojista consegue garantir URLs únicas e organizadas, adaptadas às necessidades de cada política comercial ⚙️.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/urls \
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "productId": 1,
6    "url": "tech-brand-product",
7    "tradePolicyId": 1,
8    "active":true
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "tradePolicyId": 1,
3  "url": "/tech-brand-product",
4  "entity": null,
5  "active": true,
6  "redirect": false,
7  "redirectCode": null,
8  "target": null,
9  "createdAt": "",
10  "updatedAt": "",
11  "productId": 1,
12  "productCategoryId": null,
13  "productBrandId": null,
14  "productPageId": null
15}

⚠️ 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.

Atualização de url

Descrição

Endpoint responsável por atualizar uma URL existente 🔗.

Atua em contexto administrativo, permitindo que o lojista modifique o endereço de acesso de uma entidade na loja.

Entre as entidades, estão:

• Produto
• Categoria
• Página
• Marca

Por meio desse endpoint, é possível configurar a URL como padrão ou como redirecionamento (redirect), conforme a necessidade.

Dessa forma, o lojista consegue ajustar URLs e controlar redirecionamentos, garantindo consistência na navegação e evitando problemas como links quebrados ou conteúdo duplicado ⚙️.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/urls \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "productId": 1, 
6    "url": "/minha-url-teste",
7    "base": "/minha-url-teste-nova",
8    "redirect": true,
9    "tradePolicyId": 1,
10    "active": true
11  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2	"status": true,
3	"data": {
4		"tradePolicyId": 1,
5		"url": "/minha-url-teste-nova",
6		"entity": null,
7		"active": false,
8		"redirect": false,
9		"redirectCode": null,
10		"target": null,
11		"createdAt": "",
12		"updatedAt": "",
13		"productId": 1,
14		"productCategoryId": null,
15		"productBrandId": null,
16		"productPageId": null
17	}
18}

⚠️ 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.

Exclusão de Url em massa

Descrição

Endpoint responsável por permitir a exclusão de múltiplas URLs em uma única operação 🗑️.

Atua em contexto administrativo, possibilitando que o lojista gerencie a remoção de URLs de forma mais ágil e eficiente.

Por meio desse endpoint, é possível excluir diversas URLs de uma só vez, facilitando a limpeza e organização da estrutura de endereços da loja.

Essa abordagem é especialmente útil em cenários com grande volume de URLs, reduzindo o esforço manual e otimizando o gerenciamento.

Dessa forma, o lojista consegue manter as URLs atualizadas e consistentes, evitando acessos inválidos ou conteúdos desnecessários ⚙️.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/products/urls/mass-remove \
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "urls": [
6      {
7        "tradePolicyId": 1,
8        "url": "/tech-brand-product"
9      }
10    ]
11  }'

✅ 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.

Exclusão de Url

Descrição

Endpoint responsável por permitir a exclusão de uma URL cadastrada na loja 🗑️.

Atua em contexto administrativo, possibilitando que o lojista remova endereços que não devem mais estar disponíveis no sistema.

Para realizar a exclusão, é obrigatório informar:

• a política comercial vinculada à URL
• a URL completa, contendo todo o caminho até o final (ex.: produto-exemplo.html)

⚠️ Importante: a URL deve ser enviada exatamente como está cadastrada no sistema, garantindo que a remoção ocorra corretamente.

Dessa forma, o lojista consegue manter a estrutura de URLs organizada e atualizada, evitando acessos inválidos ou conteúdos obsoletos ⚙️.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/urls \
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "url": "tech-brand-product",
6    "tradePolicyId": 1
7  }'

✅ 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.