Skip to content

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.

    Notas e Considerações

  • 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 ⚙️.

Criação e atualização de descrições

PUT /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

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

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
productsarray✅Lista de descrições que devem ser cadastradas (max 100)
products.*.productIdintegerobrigatório se não houver nenhuma outra entidade definidaIdentificador único de um produto
products.*.productBrandIdintegerobrigatório se não houver nenhuma outra entidade definidaIdentificador único de uma marca
products.*.productPageIdintegerobrigatório se não houver nenhuma outra entidade definidaIdentificador único de um página
products.*.productCategoryIdintegerobrigatório se não houver nenhuma outra entidade definidaIdentificador único de um categoria
products.*.tradePolicyIdinteger✅Identificador da politica comercial que a descrição vai pertencer
products.*.namestring✅Nome da entidade vinculada na descrição (max 255)
products.*.shortDescriptionstring✅Descrição curta da entidade vinculada (max 255)
products.*.videoUrlstring✅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 InternoCódigo HttpDescrição
UAPPI_CORE_INVALID_TRADE_POLICY_ID400Os ids de política comercial solicitados não são permitidos.
UAPPI_STORE_INVALID_DESCRIPTION_ENTITY400A entidade solicitada para criar a descrição não foi encontrada.

Atualização de dados customizados da descrição

PUT /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
  • 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:

  • Descrição longa, com conteúdo rico e detalhado
  • Tabela de medidas, com estrutura personalizada
  • 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:

  • Página
  • Produto
  • Marca
  • Categoria

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

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

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
productsarray✅Lista de descrições que devem ser atualizadas (max 100)
products.*.productIdintegerobrigatório se não houver nenhuma outra entidade definidaIdentificador único de um produto
products.*.productBrandIdintegerobrigatório se não houver nenhuma outra entidade definidaIdentificador único de uma marca
products.*.productPageIdintegerobrigatório se não houver nenhuma outra entidade definidaIdentificador único de um página
products.*.productCategoryIdintegerobrigatório se não houver nenhuma outra entidade definidaIdentificador único de um categoria
products.*.tradePolicyIdinteger❌Id único de uma politica vínculada a um produto
products.*.searchDescriptionstring❌Descrição de um produto para uso em um navegador (max 65535)
products.*.descriptionstring❌Descrição do produto (max 16777215)
products.*.customDescription1string❌Descrição personalizada 1 (max 16777215)
products.*.customDescription2string❌Descrição personalizada 2 (max 16777215)
products.*.customDescription3string❌Descrição personalizada 3 (max 16777215)
products.*.measureTablestring❌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": 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 InternoCódigo HttpDescrição
UAPPI_CORE_INVALID_TRADE_POLICY_ID400Os ids de política comercial solicitados não são permitidos.
UAPPI_STORE_INVALID_DESCRIPTION_ENTITY400A entidade solicitada para criar a descrição não foi encontrada.

Atualização de dados de SEO das descrições

PUT /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
  • 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:

  • 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
  • Essas definições são essenciais para:

  • 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

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

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

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
productsarray✅Lista de descrições que devem ser atualizadas (max 100)
products.*.productIdintegerobrigatório se não houver nenhuma outra entidade definidaIdentificador único de um produto
products.*.productBrandIdintegerobrigatório se não houver nenhuma outra entidade definidaIdentificador único de uma marca
products.*.productPageIdintegerobrigatório se não houver nenhuma outra entidade definidaIdentificador único de um página
products.*.productCategoryIdintegerobrigatório se não houver nenhuma outra entidade definidaIdentificador único de um categoria
products.*.tradePolicyIdstring✅Id único de uma politica comercial a ser vínculada
products.*.seoTitlestring✅Título do produto pensado em SEO
products.*.seoDescriptionstring✅Descrição voltada para mecanismos de busca, geralmente utilizada como meta description.
products.*.seoKeywordsstring✅Palavras-chave relacionadas ao produto (campo complementar para estratégia de SEO).
products.*.seoCanonicalstring✅URL canônica da página do produto, utilizada para evitar conteúdo duplicado nos buscadores.
products.*.seoSocialTitlestring✅ítulo exibido ao compartilhar o produto em redes sociais.
products.*.seoSocialDescriptionstring✅Descrição exibida em compartilhamentos sociais.
products.*.seoTwitterlImageUrlstring✅URL da imagem utilizada para compartilhamento no Twitter (Twitter Card).
products.*.seoGraphImageUrlstring✅URL da imagem utilizada no padrão Open Graph (exibida em redes como Facebook e LinkedIn).
products.*.seoIndexOnGoogleboolean✅Define se o produto deve ser indexado pelo Google (true ou false).
products.*.seoGoogleCategoryIdstring✅ID da categoria do Google Shopping associada ao produto.
products.*.seoGoogleConditionstring✅Condição do produto para o Google (ex.: novo, usado, recondicionado).
products.*.seoGoogleAgeGroupstring✅Faixa etária aplicável ao produto (quando exigido pelo Google).
products.*.seoGoogleGenderstring✅Gênero aplicável ao produto (quando necessário para categorização no Google).
products.*.seoStructuredDataobject✅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": null
64}

⚠️ 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_CORE_INVALID_TRADE_POLICY_ID400Os ids de política comercial solicitados não são permitidos.
UAPPI_STORE_INVALID_DESCRIPTION_ENTITY400A entidade solicitada para criar a descrição não foi encontrada.

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

;