Documentação de Descrições
Visão Geral
A descrição é responsável por armazenar os conteúdos textuais e informativos de uma entidade da loja 📝.
Ela permite definir informações exibidas ao cliente, como descrições longas, conteúdos personalizados, textos institucionais e informações complementares, podendo variar conforme o contexto.
Um ponto importante é que a descrição é vinculada a uma política comercial, possibilitando que uma mesma entidade possua diferentes versões de conteúdo, dependendo da estratégia aplicada.
Além disso, os conteúdos são flexíveis e suportam HTML, permitindo maior liberdade na formatação e apresentação das informações no front-end.
Entidades Envolvidas
- Descrição (Description) Entidade responsável por armazenar os conteúdos textuais.
- Produto (Product)
- Categoria (Category)
- Marca (Brand)
- Página (Page) A descrição pode ser vinculada a apenas uma dessas entidades por vez.
- Política Comercial (Trade Policy) Define o contexto no qual a descrição será aplicada.
- Apenas uma entidade pode ser vinculada por operação.
- Uma mesma entidade pode possuir múltiplas descrições, desde que em políticas comerciais diferentes.
- Os conteúdos aceitam HTML, sendo renderizados diretamente no front-end.
- Ideal para SEO, conteúdo rico e personalização da experiência do usuário ⚙️.
Notas e Considerações
Criação e atualização de descrições
/products/descriptions
Permite cadastrar descrições de diversas entidades da loja
Descrição
Endpoint responsável por cadastrar descrições vinculadas a entidades específicas 📝.Atua em contexto administrativo, permitindo que o lojista gerencie conteúdos descritivos de diferentes entidades da plataforma.
Por meio desse endpoint, é possível associar uma descrição a um único tipo de entidade por vez, podendo ser:
- Produto
- Marca
- Categoria
- Página
⚠️ Importante: a requisição aceita apenas um vínculo por operação, não sendo possível associar múltiplos tipos de entidade simultaneamente.
A descrição será vinculada exclusivamente à entidade informada, garantindo que o conteúdo seja corretamente aplicado no contexto desejado.
Variação por política comercial: a descrição também deve ser associada a uma política comercial específica.
Isso permite que uma mesma entidade possua múltiplas versões de descrição, variando conforme a política comercial aplicada.
Dessa forma, o lojista consegue personalizar conteúdos de acordo com diferentes contextos de venda, adaptando a comunicação conforme a estratégia de cada política ⚙️.
Headers Obrigatórios
| Header | Valor | Descrição |
|---|---|---|
Content-Type | application/json | Tipo de conteúdo |
Authorization | Bearer {userToken} | Token de autenticação |
Parâmetros do Corpo
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
products | array | ✅ | Lista de descrições que devem ser cadastradas (max 100) |
products.*.productId | integer | obrigatório se não houver nenhuma outra entidade definida | Identificador único de um produto |
products.*.productBrandId | integer | obrigatório se não houver nenhuma outra entidade definida | Identificador único de uma marca |
products.*.productPageId | integer | obrigatório se não houver nenhuma outra entidade definida | Identificador único de um página |
products.*.productCategoryId | integer | obrigatório se não houver nenhuma outra entidade definida | Identificador único de um categoria |
products.*.tradePolicyId | integer | ✅ | Identificador da politica comercial que a descrição vai pertencer |
products.*.name | string | ✅ | Nome da entidade vinculada na descrição (max 255) |
products.*.shortDescription | string | ✅ | Descrição curta da entidade vinculada (max 255) |
products.*.videoUrl | string | ✅ | Url de video da entidade vinculada (max 255) |
Exemplo de Requisição
1curl --request PUT \2 --url {{MAIN_URL}}/products/descriptions \3 --header "Authorization: Bearer userToken" \4 --data '{5 "products": [6 {7 "productId": 1,8 "tradePolicyId": 1,9 "name": "Whey muito concentrado",10 "shortDescription": "Mais proteína no seu whey",11 "videoUrl": "www.youtube.com"12 }13 ]14 }'✅ Resposta de Sucesso
HTTP Status: 200 OK
1{2 "tradePolicyId": 1,3 "name": "Whey muito mais concentrado",4 "shortDescription": "Prepare o lacday",5 "videoUrl": "www.youtube.com",6 "searchDescription": null,7 "description": null,8 "customDescription1": null,9 "customDescription2": null,10 "customDescription3": null,11 "measureTable": null,12 "seoTitle": null,13 "seoDescription": null,14 "seoKeywords": null,15 "seoCanonical": null,16 "seoSocialTitle": null,17 "seoSocialDescription": null,18 "seoTwitterImageUrl": null,19 "seoGraphImageUrl": null,20 "seoGoogleCategoryId": null,21 "seoIndexOnGoogle": null,22 "seoGoogleCondition": null,23 "seoGoogleAgeGroup": null,24 "seoGoogleGender": null,25 "seoStructuredData": null,26 "error": "",27 "productId": 1,28 "productCategoryId": null,29 "productBrandId": null,30 "productPageId": null 31}⚠️ 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 Interno | Código Http | Descrição |
|---|---|---|
| UAPPI_CORE_INVALID_TRADE_POLICY_ID | 400 | Os ids de política comercial solicitados não são permitidos. |
| UAPPI_STORE_INVALID_DESCRIPTION_ENTITY | 400 | A entidade solicitada para criar a descrição não foi encontrada. |
Atualização de dados customizados da descrição
/products/descriptions/custom
Permite que o lojista atualize informações customizadas da descrição
Descrição
Endpoint responsável por cadastrar ou atualizar conteúdos customizados de uma descrição 📝.
Atua em contexto administrativo, permitindo que o lojista gerencie diferentes tipos de conteúdo exibidos nas páginas da plataforma.
Por meio desse endpoint, é possível definir e segmentar múltiplos tipos de conteúdo, como:
- Descrição customizada 1, 2 e 3
- Descrição de busca da entidade
- Descrição longa da entidade
- Tabela de medidas
- Descrição longa, com conteúdo rico e detalhado
- Tabela de medidas, com estrutura personalizada
- Página
- Produto
- Marca
- Categoria
Esses campos são flexíveis e aceitam conteúdo em HTML, permitindo que o lojista defina livremente a formatação.
Na prática, os usos mais comuns são:
O conteúdo é apenas renderizado pelo front-end, respeitando a formatação enviada ⚙️.
⚠️ Importante: para atualização, é necessário informar qual entidade será associada, podendo ser:
A requisição permite apenas uma entidade por vez, garantindo que o conteúdo seja vinculado corretamente ao contexto desejado.
Parâmetros
Headers Obrigatórios
| Header | Valor | Descrição |
|---|---|---|
Content-Type | application/json | Tipo de conteúdo |
Authorization | Bearer {userToken} | Token de autenticação |
Parâmetros do Corpo
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
products | array | ✅ | Lista de descrições que devem ser atualizadas (max 100) |
products.*.productId | integer | obrigatório se não houver nenhuma outra entidade definida | Identificador único de um produto |
products.*.productBrandId | integer | obrigatório se não houver nenhuma outra entidade definida | Identificador único de uma marca |
products.*.productPageId | integer | obrigatório se não houver nenhuma outra entidade definida | Identificador único de um página |
products.*.productCategoryId | integer | obrigatório se não houver nenhuma outra entidade definida | Identificador único de um categoria |
products.*.tradePolicyId | integer | ❌ | Id único de uma politica vínculada a um produto |
products.*.searchDescription | string | ❌ | Descrição de um produto para uso em um navegador (max 65535) |
products.*.description | string | ❌ | Descrição do produto (max 16777215) |
products.*.customDescription1 | string | ❌ | Descrição personalizada 1 (max 16777215) |
products.*.customDescription2 | string | ❌ | Descrição personalizada 2 (max 16777215) |
products.*.customDescription3 | string | ❌ | Descrição personalizada 3 (max 16777215) |
products.*.measureTable | string | ❌ | descrição complementar do produto com aceitação de html (max 16777215) |
Exemplo de Requisição
1curl --request PUT \2 --url {{MAIN_URL}}/products/descriptions/custom \3 --header "Authorization: Bearer userToken" \4 --data '{5 "products": [6 {7 "productCategoryId": 1,8 "tradePolicyId": 1,9 "searchDescription": "Encontre os melhores produtos da categoria com qualidade garantida e entrega rápida para todo o Brasil.",10 "description": "Esta categoria reúne uma seleção exclusiva de produtos desenvolvidos para oferecer desempenho, durabilidade e excelente custo-benefício no dia a dia.",11 "customDescription1": "Destaque: produtos com alta avaliação dos clientes e recomendados por especialistas do mercado.",12 "customDescription2": "Aproveite condições especiais de pagamento, incluindo parcelamento sem juros e descontos à vista.",13 "customDescription3": "Envio rápido e seguro com acompanhamento em tempo real do seu pedido.",14 "measureTable": "<table><tr><th>Tamanho</th><th>Largura</th><th>Altura</th></tr><tr><td>P</td><td>50 cm</td><td>70 cm</td></tr><tr><td>M</td><td>60 cm</td><td>80 cm</td></tr><tr><td>G</td><td>70 cm</td><td>90 cm</td></tr></table>"15 }16 ]17 }'✅ Resposta de Sucesso
HTTP Status: 200 OK
1{2 "tradePolicyId": 1,3 "name": null,4 "shortDescription": null,5 "videoUrl": null,6 "searchDescription": "Encontre os melhores produtos da categoria com qualidade garantida e entrega rápida para todo o Brasil.",7 "description": "Esta categoria reúne uma seleção exclusiva de produtos desenvolvidos para oferecer desempenho, durabilidade e excelente custo-benefício no dia a dia.",8 "customDescription1": "Destaque: produtos com alta avaliação dos clientes e recomendados por especialistas do mercado.",9 "customDescription2": "Aproveite condições especiais de pagamento, incluindo parcelamento sem juros e descontos à vista.",10 "customDescription3": "Envio rápido e seguro com acompanhamento em tempo real do seu pedido.",11 "measureTable": "<table><tr><th>Tamanho</th><th>Largura</th><th>Altura</th></tr><tr><td>P</td><td>50 cm</td><td>70 cm</td></tr><tr><td>M</td><td>60 cm</td><td>80 cm</td></tr><tr><td>G</td><td>70 cm</td><td>90 cm</td></tr></table>", 12 "seoTitle": null,13 "seoDescription": null,14 "seoKeywords": null,15 "seoCanonical": null,16 "seoSocialTitle": null,17 "seoSocialDescription": null,18 "seoTwitterImageUrl": null,19 "seoGraphImageUrl": null,20 "seoGoogleCategoryId": null,21 "seoIndexOnGoogle": null,22 "seoGoogleCondition": null,23 "seoGoogleAgeGroup": null,24 "seoGoogleGender": null,25 "seoStructuredData": null,26 "error": "",27 "productId": null,28 "productCategoryId": 1,29 "productBrandId": null,30 "productPageId": null31}⚠️ 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 Interno | Código Http | Descrição |
|---|---|---|
| UAPPI_CORE_INVALID_TRADE_POLICY_ID | 400 | Os ids de política comercial solicitados não são permitidos. |
| UAPPI_STORE_INVALID_DESCRIPTION_ENTITY | 400 | A entidade solicitada para criar a descrição não foi encontrada. |
Atualização de dados de SEO das descrições
/products/descriptions/seo
Permite que o lojista defina dados de SEO nas descrições
Descrição
Este endpoint permite configurar os metadados de SEO e indexação de uma entidade 🧭, abrangendo sua exibição em mecanismos de busca, redes sociais e integrações externas, como o Google Shopping.
Atua em contexto administrativo, centralizando todas as definições que impactam como o conteúdo será apresentado fora da loja, influenciando diretamente a visibilidade orgânica e a forma como ele é exibido em diferentes canais.
⚠️ Importante: para atualização, é necessário informar qual entidade será associada, podendo ser:
- Página
- Produto
- Marca
- Categoria
- Como a página aparece nos resultados de busca (título, descrição e indexação)
- Como o conteúdo é exibido ao ser compartilhado em redes sociais (preview com imagem, título e descrição)
- Como a entidade é interpretada por integrações externas, como o Google Shopping
- Melhorar o ranqueamento em buscadores (SEO) 📈
- Garantir consistência na apresentação do conteúdo em diferentes canais
- Aumentar a taxa de cliques (CTR) ao exibir informações mais atrativas
- Atender aos padrões exigidos por plataformas externas
A requisição permite apenas uma entidade por vez, garantindo que as configurações sejam aplicadas corretamente ao contexto desejado.
Abrangência das configurações: por meio deste endpoint, é possível controlar:
Essas definições são essenciais para:
Dessa forma, o lojista consegue controlar de forma estratégica a presença digital da loja, otimizando tanto a descoberta quanto a apresentação dos produtos e conteúdos ⚙️.
Headers Obrigatórios
| Header | Valor | Descrição |
|---|---|---|
Content-Type | application/json | Tipo de conteúdo |
Authorization | Bearer {userToken} | Token de autenticação |
Parâmetros do Corpo
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
products | array | ✅ | Lista de descrições que devem ser atualizadas (max 100) |
products.*.productId | integer | obrigatório se não houver nenhuma outra entidade definida | Identificador único de um produto |
products.*.productBrandId | integer | obrigatório se não houver nenhuma outra entidade definida | Identificador único de uma marca |
products.*.productPageId | integer | obrigatório se não houver nenhuma outra entidade definida | Identificador único de um página |
products.*.productCategoryId | integer | obrigatório se não houver nenhuma outra entidade definida | Identificador único de um categoria |
products.*.tradePolicyId | string | ✅ | Id único de uma politica comercial a ser vínculada |
products.*.seoTitle | string | ✅ | Título do produto pensado em SEO |
products.*.seoDescription | string | ✅ | Descrição voltada para mecanismos de busca, geralmente utilizada como meta description. |
products.*.seoKeywords | string | ✅ | Palavras-chave relacionadas ao produto (campo complementar para estratégia de SEO). |
products.*.seoCanonical | string | ✅ | URL canônica da página do produto, utilizada para evitar conteúdo duplicado nos buscadores. |
products.*.seoSocialTitle | string | ✅ | ítulo exibido ao compartilhar o produto em redes sociais. |
products.*.seoSocialDescription | string | ✅ | Descrição exibida em compartilhamentos sociais. |
products.*.seoTwitterlImageUrl | string | ✅ | URL da imagem utilizada para compartilhamento no Twitter (Twitter Card). |
products.*.seoGraphImageUrl | string | ✅ | URL da imagem utilizada no padrão Open Graph (exibida em redes como Facebook e LinkedIn). |
products.*.seoIndexOnGoogle | boolean | ✅ | Define se o produto deve ser indexado pelo Google (true ou false). |
products.*.seoGoogleCategoryId | string | ✅ | ID da categoria do Google Shopping associada ao produto. |
products.*.seoGoogleCondition | string | ✅ | Condição do produto para o Google (ex.: novo, usado, recondicionado). |
products.*.seoGoogleAgeGroup | string | ✅ | Faixa etária aplicável ao produto (quando exigido pelo Google). |
products.*.seoGoogleGender | string | ✅ | Gênero aplicável ao produto (quando necessário para categorização no Google). |
products.*.seoStructuredData | object | ✅ | Objeto complementar para enriquecer os dados estruturados. |
Exemplo de Requisição
1curl --request PUT \2 --url {{MAIN_URL}}/products/descriptions/seo\3 --header "Authorization: Bearer userToken" \4 --data '{5 "products": [6 {7 "productId": 1,8 "tradePolicyId": 3,9 "seoTitle": "exampleSeoTitle",10 "seoDescription": "A SEO Description",11 "seoKeywords": "A SEO Keyword",12 "seoCanonical": "a-seo-canonical-url",13 "seoSocialTitle": "A SEO Social Title",14 "seoSocialDescription": "A SEO Social Description",15 "seoTwitterlImageUrl": "image-twitter-url",16 "seoGraphImageUrl": "image-url-for-open-graph",17 "seoGoogleCategoryId": 1,18 "seoIndexOnGoogle": true,19 "seoGoogleCondition": "seoConditionOnGoogle",20 "seoGoogleAgeGroup": "seoGoogleAgeGroup",21 "seoGoogleGender": "seoGoogleGender",22 "seoStructuredData": {23 "alternateName": "Alternate Name",24 "modelName": "Model Name",25 "audience": {26 "type": "BusinessAudience|EducationalAudience|MedicalAudience|PeopleAudience|Researcher"27 "audienceType": "Pacientes adultos com peso superior a 30 kg"28 },29 "isRelatedTo": [30 {31 "type": "MedicalCondition",32 "name": "Apneia obstrutiva do sono"33 },34 {35 "type": "https://schema.org/Thing|MedicalCondition|ControlAction",36 "name": "Ronco"37 }38 ],39 "additionalProperty": [40 {41 "name": "Pré-aquecimento",42 "value": "Modo de pré-aquecimento do umidificador antes do início da terapia"43 },44 {45 "name": "Tubo aquecido",46 "value": "Controle inteligente da temperatura do ar para reduzir condensação no tubo e na máscara"47 }48 ],49 "faq": [50 {51 "question": "Esse produto é 220v?",52 "answer": "Sim, esse produto é caracterizado como \"bivolt\" e é compatível com 220v."53 }54 ]55 }56 }57 ]58 }'✅ Resposta de Sucesso
HTTP Status: 200 OK
1{2 "tradePolicyId": 1,3 "name": null,4 "shortDescription": null,5 "videoUrl": null,6 "searchDescription": null,7 "description": null,8 "customDescription1": null,9 "customDescription2": null,10 "customDescription3": null,11 "measureTable": null,12 "seoTitle": "exampleSeoTitle",13 "seoDescription": "A SEO Description",14 "seoKeywords": "A SEO Keyword",15 "seoCanonical": "a-seo-canonical-url",16 "seoSocialTitle": "A SEO Social Title",17 "seoSocialDescription": "A SEO Social Description",18 "seoTwitterImageUrl": null,19 "seoGraphImageUrl": "image-url-for-open-graph",20 "seoGoogleCategoryId": 1,21 "seoIndexOnGoogle": true,22 "seoGoogleCondition": "seoConditionOnGoogle",23 "seoGoogleAgeGroup": "seoGoogleAgeGroup",24 "seoGoogleGender": "seoGoogleGender",25 "seoStructuredData": {26 "alternateName": "Alternate Name",27 "modelName": "Model Name",28 "audience": {29 "type": "BusinessAudience|EducationalAudience|MedicalAudience|PeopleAudience|Researcher"30 "audienceType": "Pacientes adultos com peso superior a 30 kg"31 },32 "isRelatedTo": [33 {34 "type": "MedicalCondition",35 "name": "Apneia obstrutiva do sono"36 },37 {38 "type": "https://schema.org/Thing|MedicalCondition|ControlAction",39 "name": "Ronco"40 }41 ],42 "additionalProperty": [43 {44 "name": "Pré-aquecimento",45 "value": "Modo de pré-aquecimento do umidificador antes do início da terapia"46 },47 {48 "name": "Tubo aquecido",49 "value": "Controle inteligente da temperatura do ar para reduzir condensação no tubo e na máscara"50 }51 ],52 "faq": [53 {54 "question": "Esse produto é 220v?",55 "answer": "Sim, esse produto é caracterizado como \"bivolt\" e é compatível com 220v."56 }57 ]58 },59 "error": "",60 "productId": 1,61 "productCategoryId": null,62 "productBrandId": null,63 "productPageId": null64}⚠️ 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 Interno | Código Http | Descrição |
|---|---|---|
| UAPPI_CORE_INVALID_TRADE_POLICY_ID | 400 | Os ids de política comercial solicitados não são permitidos. |
| UAPPI_STORE_INVALID_DESCRIPTION_ENTITY | 400 | A entidade solicitada para criar a descrição não foi encontrada. |