Documentação de Produto

Visão Geral

O produto é a entidade central da loja, representando os itens disponíveis para venda ou exibição 🛍️.

Ele concentra todas as informações necessárias para comercialização, como preço, descrição, estoque, atributos, imagens, categorias e configurações específicas.

Os produtos podem ser configurados de forma flexível, permitindo:

• Criação de variações
• Definição de regras de venda
• Associação com políticas comerciais
• Personalização de conteúdo e SEO

Além disso, diversas entidades relacionadas são geradas automaticamente no momento do cadastro, garantindo que o produto esteja pronto para uso.

Entidades Envolvidas

• Produto (Product)
Entidade principal que representa o item da loja.
• Atributos e Valores (Attributes & Values)
Responsáveis por definir variações do produto.
• Categoria (Category)
Organiza o produto dentro da estrutura da loja.
• Marca (Brand)
Define o fabricante ou identidade do produto.
• Descrição (Description)
Armazena conteúdos textuais do produto.
• URL (Url)
Define o endereço de acesso do produto.
• Mídias (Media)
Representam imagens, vídeos ou documentos associados.
• Dados Fiscais, Estoque e Dimensões
Informações complementares para operação e logística.

Entre várias outras entidades do sistema, sendo um dos pontos centrais da plataforma.

Notas e Considerações

• Produtos podem possuir variações baseadas em atributos.
• Podem ser configurados para diferentes políticas comerciais.
• Diversas entidades são criadas automaticamente no cadastro inicial.
• A correta configuração impacta diretamente na experiência do usuário e operação da loja ⚙️.

Cadastro de produtos

Descrição

Endpoint responsável por permitir que o lojista cadastre novos produtos na loja 🛍️.

Atua em contexto administrativo, sendo utilizado para inserir novos itens no catálogo da plataforma.

Por meio desse endpoint, é possível criar produtos e definir suas principais informações, como descrições, categorias, marcas, atributos e demais configurações necessárias para sua exibição e comercialização.

Dessa forma, o lojista consegue expandir e organizar o catálogo da loja, garantindo que novos produtos possam ser exibidos e vendidos corretamente na plataforma ⚙️.

Processos automáticos ao cadastrar um produto: durante o cadastro, o sistema também cria automaticamente algumas entidades relacionadas ao produto.

Entre elas:

• URLs do produto geradas para cada política comercial
• Uma descrição inicial criada para cada política comercial
• Preferências padrão do produto configuradas automaticamente
• Registro inicial de dados fiscais
• Registro inicial de dimensões
• Registro inicial de estoque

Esses registros são criados como estruturas iniciais, permitindo que o lojista possa complementar e ajustar as informações posteriormente conforme necessário.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "sku": "SKU123321",
6    "name": "Techbrand - Smartphone 8gb RAM 256gb de armazenamento",
7    "brandId": 1,
8    "active": true,
9    "priority": 1,
10    "basePrice": 1599,
11    "tradePolicies": {
12      "1": true
13    }
14  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 1,
3  "brandId": 1,
4  "type": "product",
5  "sku": "SKU123321",
6  "name": "Techbrand - Smartphone 8gb RAM 256gb de armazenamento",
7  "priority": 1,
8  "basePrice": 1599,
9  "active": true,
10  "createdAt": "2026-03-16 14:05:11",
11  "updatedAt": "2026-03-16 14:05:11"
12}

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

Descrição

Endpoint responsável por permitir que o lojista atualize um produto da loja ✏️.

Atua em contexto administrativo, possibilitando a edição das informações já cadastradas de um produto.

Dessa forma, o lojista consegue manter as informações do produto sempre atualizadas, garantindo consistência e precisão nos dados exibidos no catálogo da loja ⚙️.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/{productId} \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "sku": "SKU123321",
6    "name": "Techbrand - Smartphone 8gb RAM 256gb de armazenamento",
7    "brandId": 1,
8    "active": true,
9    "priority": 1,
10    "basePrice": 1599,
11    "tradePolicies": {
12      "1": true
13    }
14  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 1,
3  "brandId": 1,
4  "type": "product",
5  "sku": "SKU123321",
6  "name": "Techbrand - Smartphone 8gb RAM 256gb de armazenamento",
7  "priority": 1,
8  "basePrice": 1599,
9  "active": true,
10  "createdAt": "2026-03-16 14:05:11",
11  "updatedAt": "2026-03-16 14:05:11"
12}

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

⚠️ Erro retornado:

1{
2  "status": false,
3  "data": {
4    "code": 429,
5    "errorCode": "THROTTLE_LIMIT_REACHED",
6    "message": "Try again in 21 seconds."
7  }
8}

Atualização de dimensões de produtos

Descrição

Endpoint responsável por atualizar as dimensões de um ou mais produtos 📦.

Atua em contexto administrativo, permitindo que o lojista gerencie informações físicas dos produtos de forma eficiente.

Por meio desse endpoint, é possível realizar atualizações em lote, enviando múltiplos produtos na mesma requisição.

Essas dimensões são utilizadas para cálculo de frete, logística e armazenamento, sendo fundamentais para o correto processamento das vendas.

Dessa forma, o lojista consegue manter os dados físicos dos produtos atualizados em escala, garantindo maior precisão nas operações logísticas ⚙️.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/dimensions \
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "products": [
6      {
7        "productId": 1,
8        "shippingCargoTypeId": null,
9        "additionalTime": 5,
10        "width": 10.123456,
11        "height": 20.12,
12        "length": 30.123,
13        "weight": 40.1234
14      },
15      {
16        "productId": 2,
17        "shippingCargoTypeId": null,
18        "additionalTime": 5,
19        "width": 10.123456,
20        "height": 20.12,
21        "length": 30.123,
22        "weight": 40.1234
23      }
24    ]
25  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  [
3    {
4      "shippingCargoTypeId": null,
5      "additionalTime": 5,
6      "width": 10.123456,
7      "height": 20.12,
8      "length": 30.123,
9      "weight": 40.1234,
10      "productId": 1,
11      "error": ""
12    },
13    {
14      "shippingCargoTypeId": null,
15      "additionalTime": 5,
16      "width": 10.123456,
17      "height": 20.12,
18      "length": 30.123,
19      "weight": 40.1234,
20      "productId": 2,
21      "error": "UAPPI_STORE_PRODUCT_NOT_FOUND"
22    }
23  ]
24}

⚠️ 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 das configurações de produto

Descrição

Endpoint responsável por atualizar as configurações de um produto da loja ⚙️.

Atua em contexto administrativo, permitindo que o lojista ajuste comportamentos importantes relacionados à venda e exibição do produto.

Por meio desse endpoint, é possível definir regras e características específicas do produto, garantindo que ele funcione corretamente dentro da lógica do catálogo e das vendas.

Entre as principais configurações que podem ser definidas estão:

• Controle de estoque mínimo
• Permitir venda sem estoque
• Exibição do produto na loja
• Definir se o produto é um serviço
• Indicar se o produto possui assinatura

Dessa forma, o lojista consegue controlar como o produto será tratado dentro da plataforma, ajustando seu comportamento conforme as necessidades do negócio 🧩.

⚠️ Comportamento da venda sem estoque

É importante observar que também não será possível fazer atualizações de estoque diretas (entrada, saída e balanço) nos produtos com venda sem estoque ativa.

A listagem e detalhe de produtos também passam a exibir o estoque disponível como 99999 e o estoque reservado para 0.

Ao inativar a venda sem estoque, o estoque disponível do produto em todos os armazéns será zerado. Os pedidos criados com produtos enquanto a venda sem estoque estiver ativa, serão concluídos normalmente.

Após a inativação, é recomendado executar um balanço ou entrada de estoque nos produtos, dessa forma os mesmos poderão continuar sendo vendidos normalmente. Para executar essas ações utilize a rota de atualização de estoque.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/flags \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5	"products": [
6		{
7			"productId": 1,
8			"subscription": true,
9			"service": true,
10			"pickUp": true,
11			"showInSite": true,
12			"saleWithoutStock": true,
13			"minimumStock": 3
14		}
15	]
16}'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "subscription": true,
6      "service": true,
7      "pickUp": true,
8      "showInSite": true,
9      "saleWithoutStock": false,
10      "minimumStock": 3,
11      "productId": 1,
12      "error": ""
13    } 
14  ]
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 dados fiscais do produto

Descrição

Endpoint responsável por permitir que o lojista defina os dados fiscais de um produto 🧾.

Atua em contexto administrativo, garantindo que o produto esteja configurado corretamente para atender às regras tributárias e fiscais exigidas pelo governo.

Por meio desse endpoint, é possível atribuir as informações fiscais necessárias ao produto, permitindo que o sistema calcule e aplique corretamente os impostos relacionados à sua venda.

Esses dados são utilizados para cumprimento das obrigações fiscais, emissão de documentos e correta tributação nas operações comerciais.

Dessa forma, o lojista consegue garantir que o produto esteja em conformidade com as regras tributárias, evitando inconsistências fiscais e problemas no processo de venda ⚙️.

---

MPN (Manufacturer Part Number)

Determina o código da peça definido pelo fabricante 🔎.

Ele identifica um produto específico dentro do catálogo do próprio fabricante, sendo muito utilizado para integração com marketplaces, ERPs e sistemas de comparação de produtos.

Diferente do EAN, ele não é padronizado globalmente, pois cada fabricante define o seu próprio código.

---

EAN (European Article Number)

Determina o código de barras do produto 📦.

Trata-se de um identificador padronizado internacionalmente, utilizado para identificar produtos no varejo, logística e sistemas de venda.

No Brasil é muito comum o EAN-13, que possui 13 dígitos. Esse código é usado em leitores de código de barras, marketplaces e sistemas fiscais.

---

NCM (Nomenclatura Comum do Mercosul)

Determina um código fiscal utilizado para classificar mercadorias 🧾.

Ele define qual é a categoria tributária do produto, sendo utilizado para cálculo de impostos, emissão de nota fiscal e cumprimento das obrigações fiscais.

Cada tipo de produto possui um NCM específico definido pela legislação.

---

Exclusive

Campo utilizado para indicar se o produto é exclusivo da própria loja ou empresa ⚙️.

Em muitos sistemas, essa flag é utilizada para representar produtos fabricados pela própria empresa, kits montados internamente ou itens sem código oficial de mercado.

Essa informação pode influenciar regras fiscais, origem da mercadoria ou tratamento tributário, dependendo das configurações do sistema. |

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/tax \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5	"products":[
6      {
7        "productId":1,
8        "mpn": "MPN-AX45-9001",
9        "ean": "7891234567895",
10        "ncm": "85176259",
11        "exclusive": false
12      }
13    ]
14  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "mpn": "MPN-AX45-9001",
3  "ean": "7891234567895",
4  "ncm": "85176259",
5  "exclusive": false,
6  "productId": 1,
7  "error": ""
8}

⚠️ Erro retornado:

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

Atualização de vínculo entre produto e marca em lote

Descrição

Endpoint responsável por permitir vincular ou desvincular produtos e marcas em lote 🔗.

Atua em contexto administrativo, possibilitando que o lojista gerencie a relação entre produtos e marcas de forma mais eficiente.

Por meio desse endpoint, é possível associar ou remover vínculos entre múltiplos produtos e uma marca, realizando a operação em massa.

Essa abordagem facilita a organização do catálogo e o gerenciamento de marcas, especialmente em cenários com grande volume de produtos ⚙️.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/brands/link \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "links":[
6      {
7        "brandId":null,
8        "productId":1
9      },
10      {
11        "brandId":1,
12        "productId":2
13      }
14    ]
15  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  [
3    {
4      "productId": 1,
5      "brandId": null
6    },
7    {
8      "productId": 2,
9      "brandId": 1
10    }
11  ]
12}

⚠️ 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 status de produto em massa

Descrição

Endpoint responsável por permitir a atualização do status de múltiplos produtos em massa 🔄.

Atua em contexto administrativo, possibilitando que o lojista altere rapidamente o status de vários produtos ao mesmo tempo.

Por meio desse endpoint, é possível aplicar mudanças de status em lote, facilitando ações como ativar, desativar ou ajustar a disponibilidade de diversos produtos de forma eficiente.

Essa abordagem ajuda a agilizar a gestão do catálogo, especialmente em cenários com grande volume de produtos ⚙️.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/status \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "products": [
6      {
7        "productId":1,
8        "active": false
9      },
10      {
11        "productId":2,
12        "active": true
13      }
14    ]
15  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2			"active": false,
3			"productId": 1,
4			"error": ""
5		},
6		{
7			"active": true,
8			"productId": 2,
9			"error": ""
10		}

⚠️ Erro retornado:

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

Exclusão de Produto

Descrição

Endpoint responsável por permitir que o lojista exclua um ou mais produtos da loja em lote.

Atua em contexto administrativo e suporta dois modos de exclusão, controlados pelo campo force de cada item:

Exclusão lógica (soft delete) — comportamento padrão

Quando force é omitido ou enviado como false, o produto não é fisicamente removido da plataforma. O campo deleted_at é preenchido com a data e hora da operação, tornando o produto invisível no catálogo e nas buscas públicas. O registro permanece armazenado e pode ser recuperado posteriormente pelo endpoint de restauração.

Exclusão permanente (hard delete)

Quando force é enviado como true, o produto é removido fisicamente da plataforma. Essa operação é irreversível — o registro não poderá ser restaurado.

Comportamento em lote e cascata

A operação recebe uma lista de produtos. Cada item é processado individualmente: falhas em um item não impedem o processamento dos demais. Quando um produto pai é removido, suas variações são automaticamente incluídas no mesmo ciclo de remoção.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

Exclusão lógica (soft delete):

1curl --request DELETE \
2  --url {{MAIN_URL}}/products \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "products": [
6      {
7        "productId": 1
8      },
9      {
10        "productId": 2
11      }
12    ]
13  }'

Exclusão permanente (hard delete):

1curl --request DELETE \
2  --url {{MAIN_URL}}/products \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "products": [
6      {
7        "productId": 1
8      },
9      {
10        "productId": 2
11      }
12    ],
13    "force": true
14  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

A resposta é um array com um objeto por produto solicitado. O campo error estará vazio em caso de sucesso, ou preenchido com o código de erro quando o produto não puder ser removido.

1{
2  "status": true,
3  "data": [
4    {
5      "productId": 1,
6      "error": null
7    },
8    {
9      "productId": 2,
10      "error": null
11    }
12  ] 
13}

⚠️ Possíveis erros:

Atenção: os erros abaixo são retornados por item, dentro do array de resposta, e não como falha HTTP global da requisição.

Restauração de Produto

Descrição

Endpoint responsável por recuperar produtos que foram excluídos de forma lógica (soft delete), tornando-os visíveis novamente no catálogo sem a necessidade de recadastrá-los.

Atua em contexto administrativo e complementa o fluxo de exclusão lógica: apenas produtos que possuem o campo deleted_at preenchido podem ser restaurados. Produtos que nunca foram removidos, ou que foram excluídos permanentemente (hard delete), não são elegíveis para restauração.

Comportamento em lote

A operação recebe uma lista de produtos. Cada item é processado individualmente: falhas em um item não impedem o processamento dos demais. O campo error de cada objeto na resposta indica se a restauração foi bem-sucedida ou qual problema ocorreu.

Cascata de variações

Ao restaurar um produto pai, suas variações que estejam em soft delete são automaticamente restauradas com ele. Não é necessário listar as variações separadamente quando o objetivo é restaurar o produto pai completo.

Restrição para variações com pai removido

Não é possível restaurar uma variação cujo produto pai ainda esteja em soft delete. O produto pai precisa estar ativo para que suas variações possam ser restauradas individualmente. Para restaurar uma variação nessa situação, restaure primeiro o produto pai.

Parâmetros

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/restore \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "products": [
6      {
7        "productId": 1
8      },
9      {
10        "productId": 2
11      }
12    ]
13  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

A resposta é um array com um objeto por produto solicitado. O campo error estará vazio em caso de sucesso, ou preenchido com o código de erro quando o produto não puder ser restaurado.

1{
2  "status": true,
3  "data": [
4    {
5      "productId": 1,
6      "error": null
7    },
8    {
9      "productId": 2,
10      "error": null
11    }
12  ]
13}

⚠️ Possíveis erros:

Atenção: os erros abaixo são retornados por item, dentro do array de resposta, e não como falha HTTP global da requisição.