Skip to content

Documentação de Mídias

Visão Geral

As mídias representam os arquivos visuais e informativos associados às entidades da loja 📸.

Elas podem incluir imagens, documentos ou links, sendo utilizadas principalmente para enriquecer a apresentação dos produtos.

As mídias podem ser vinculadas a produtos e valores de atributos, permitindo desde a exibição de galerias até representações específicas de variações (ex.: cor do produto).

A ordem em que as mídias são vinculadas é relevante, pois define a sequência de exibição no front-end.

Entidades Envolvidas

  • Mídia (Media)
    • Representa o arquivo em si (imagem, vídeo, etc.).

  • Produto (Product)
    • Principal entidade que consome mídias para exibição.

  • Valor de Atributo (Attribute Value)
    • Pode possuir mídias associadas para representação visual.

    Otimização de imagens

    A plataforma possui recursos para otimizar as mídias do tipo image, gerando imagens derivadas em tamanhos diferentes, dessa forma os fronts das lojas podem escolher qual o melhor tamanho para utilização.

    Quando não há configuração customizada da loja, o processamento usa os seguintes valores padrão para gerar derivadas:

    PerfilPrefixoLargura padrão (px)Altura padrão (px)Qualidade padrão (%)Cor de preenchimento padrão (hexadecimal)
    Pequenos_24024090ffffff
    Médiom_48048090ffffff
    Grandeb_96096090ffffff
    Caso seja necessário atualizar essas configurações, utilize os recursos de configurações da plataforma.

    Notas e Considerações

  • É possível vincular múltiplas mídias a uma mesma entidade.
  • A ordem de vínculo define a ordem de exibição.
  • Mídias são essenciais para experiência visual e conversão de vendas.
  • A exclusão de mídias pode impactar diretamente a apresentação do produto ⚠️.

Listagem de mídia de produtos

GET /products/medias

Possibilita que o lojista veja uma lista das mídias cadastradas na loja

Descrição

Endpoint responsável por retornar a lista de mídias de produtos cadastradas 🖼️.

Atua em contexto administrativo, permitindo que o lojista visualize os arquivos associados aos produtos da plataforma.

Por meio desse endpoint, é possível consultar as mídias cadastradas, como imagens, links e documentos vinculados aos produtos.

Dessa forma, o lojista consegue gerenciar e revisar os conteúdos visuais disponíveis, garantindo organização e consistência na apresentação dos produtos ⚙️.

Headers Obrigatórios

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

Campos de Condição Disponíveis

CampoTipoDescrição
idintegerID da mídia
titlestringTítulo da mídia
typestringTipo do midia (image, file, url)
urlstringUrl que direciona para a mídia desejada
filestringArquivo da mídia cadastrada

Campos de Ordenação Disponíveis

CampoDescrição
IdIdentificador da mídia

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 198,
7        "type": "file",
8        "title": "Certificado",
9        "alternativeText": "certificado",
10        "file": "/upload/stores/1/upload/media/0319b173c75b4d9c72ccfa47f653f9f8.pdf",
11        "originalFile": "/upload/stores/1/upload/media/0319b173c75b4d9c72ccfa47f653f9f8.pdf",
12        "size": 141846,
13        "originalSize": 141846,
14        "width": null,
15        "height": null,
16        "url": null,
17        "imageProcessed": false,
18        "imageSize": null
19      },
20      {
21        "id": 199,
22        "type": "image",
23        "title": "Foto Principal",
24        "alternativeText": "foto-principal",
25        "file": "/upload/stores/1/upload/media/c455a25c7d9d407e659ce4ae0df9ab36.webp",
26        "originalFile": "/upload/stores/1/upload/media/2c2732fe9a1492933c19335205b1477d.png",
27        "size": 91854,
28        "originalSize": 397253,
29        "width": 2076,
30        "height": 1492,
31        "url": null,
32        "imageProcessed": false,
33        "imageSize": {
34          "smallWebp": "/upload/stores/1/upload/media/c455a25c7d9d407e659ce4ae0df9ab36.webp",
35          "small": "/upload/stores/1/upload/media/2c2732fe9a1492933c19335205b1477d.png",
36          "mediumWebp": "/upload/stores/1/upload/media/c455a25c7d9d407e659ce4ae0df9ab36.webp",
37          "medium": "/upload/stores/1/upload/media/2c2732fe9a1492933c19335205b1477d.png",
38          "bigWebp": "/upload/stores/1/upload/media/c455a25c7d9d407e659ce4ae0df9ab36.webp",
39          "big": "/upload/stores/1/upload/media/2c2732fe9a1492933c19335205b1477d.png"
40        }
41      }
42    ],
43    "pagination": {
44      "limit": 10,
45      "offset": 0,
46      "pages": 1,
47      "registers": 2
48    }
49  }
50}

Cadastrar midias de produtos

POST /products/medias

Permite atribuir midias como documentos, imagens e links a produtos

Descrição

Este endpoint permite cadastrar mídias no sistema, podendo ser:

  • uma imagem,
  • um arquivo (PDF),
  • ou um link (URL).

No envio da requisição, é obrigatório informar pelo menos uma mídia dentro da lista medias.

O tipo escolhido determina o que deve ser enviado. Quando a mídia for do tipo image, é obrigatório anexar o arquivo da imagem, que deve estar nos formatos JPG ou PNG e ter no máximo 3MB.

Se o tipo for file, é obrigatório anexar um arquivo no formato PDF.

Já quando o tipo for url, é obrigatório informar um link válido.

Headers Obrigatórios

HeaderValorDescrição
Content-Typemultipart/form-dataTipo do conteúdo
AuthorizationBearer {userToken}Token de autenticação

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
mediaarray✅Lista de mídias a serem criadas.
media.*.titlestring❌Título da mídia (max 255 caracteres)
media.*.altenativeTextstring❌Texto descritivo da mídia (max 255)
media.*.typestring✅TIpo da mídia a ser cadastrada (file, image, url)
media.*.imagefile✅Arquivo de imagem a ser cadastrado (extensão: jpeg, png, jpg; max: 3mb)
media.*.filefile✅Documento a ser cadastrado (formato: PDF)
media.*.urlstring✅Url que direcione para uma imagem ou documento

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/medias \
3  --header "Authorization: Bearer userToken" \
4  --form "medias[0][title]=Imagem legal" \
5  --form "medias[0][alternativeText]=Descrição da imagem 1" \
6  --form "medias[0][type]=image" \
7  --form "medias[0][file]=@/caminho/imagem1.png"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "type": "image",
6    "title": "PimPom",
7    "alternativeText": "ursinho-pimpom",
8    "file": "/upload/media/98765432198764531243987654321.webp",
9    "originalFile": "/upload/media/98765432198764531243987654321.jpeg",
10    "size": 264170,
11    "originalSize": 68533,
12    "width": 681,
13    "height": 542,
14    "url": null,
15    "imageProcessed": false
16  }
17}

Atualizar midias de produtos

PUT /products/medias/{mediaId}

Permite que o lojista possa atualizar midias de produtos

Descrição

Endpoint responsável por atualizar uma imagem existente 🖼️.

Atua em contexto administrativo, permitindo que o lojista modifique imagens já cadastradas no sistema.

Por meio desse endpoint, é possível substituir ou ajustar uma imagem, garantindo que o conteúdo visual esteja sempre atualizado.

Dessa forma, o lojista consegue manter a qualidade e consistência das mídias da loja, refletindo corretamente as informações visuais dos produtos ou entidades associadas ⚙️.

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
mediaIdintegerSimIdentificador da mídia que vai ser alterada

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
titlestring❌Título de identificação da mídia
alternativeTextstring❌Texto descritivo sobre a mídia
urlstring❌Link que direcione para a mídia
fileNamestring❌Nome do arquivo da mídia

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/medias/{mediaId} \
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "title": "UappiTest",
6    "url": "https://site-legal/product/media/92837691238759827.jpg",
7    "alternativeText": "A beautiful Image",
8    "fileName": "A new random file"
9  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "id": 1,
3  "type": "image",
4  "title": "UappiTest",
5  "alternativeText": "A beautiful Image",
6  "file": "/upload/stores/upload/media/a-new-random-file.webp",
7  "originalFile": "/upload/stores/1/upload/media/a-new-random-file.jpeg",
8  "size": 264170,
9  "originalSize": 68533,
10  "width": 681,
11  "height": 542,
12  "url": null
13}

⚠️ 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_PRODUCT_MEDIA_REQUIRE_URL400A mídia de produto requer URL.
UAPPI_STORE_PRODUCT_MEDIA_NOT_FOUND404A mídia solicitada não foi encontrada.
UAPPI_STORE_PRODUCT_MEDIA_DOES_NOT_USE_FILE400A mídia de produto solicitada não utiliza arquivo.
UAPPI_STORE_PRODUCT_MEDIA_FILE_NOT_FOUND404O arquivo da mídia de produto solicitada não foi encontrado.

Vínculo entre uma mídia e um produto

PUT /products/medias/links

Criação de vinculo entre uma mídia e um produto

Descrição

Endpoint responsável por criar vínculo entre uma ou mais mídias e um produto 🖼️.

Atua em contexto administrativo, permitindo que o lojista associe imagens, links ou documentos à página de um produto.

Por meio desse endpoint, é possível vincular múltiplas mídias em uma única operação, desde que os IDs sejam enviados separados por vírgula.

⚠️ Importante: a ordem dos IDs informados será respeitada como a ordem de exibição na página do produto.

Isso permite organizar a sequência visual das mídias, garantindo que a apresentação siga a estratégia desejada.

Essa estrutura é especialmente útil em cenários como:

  • Galerias de produto
    • Permite definir a sequência ideal de exibição das imagens, como imagem principal, detalhes, zoom e ângulos diferentes, criando uma apresentação mais completa do produto.

  • Exibição de variações por atributo
    • Possibilita associar mídias específicas a variações, como por exemplo: ao selecionar a cor azul, exibir apenas imagens daquele modelo na cor azul 🎨. Isso torna a navegação mais intuitiva e evita confusão para o cliente.

  • Organização de imagens principais e secundárias
Permite destacar uma imagem principal (capa) e manter outras como secundárias, garantindo que a primeira impressão do produto seja estratégica e mais atrativa.

Dessa forma, o lojista consegue controlar a experiência visual do produto de forma mais avançada, melhorando a apresentação e auxiliando na decisão de compra ⚙️.

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
forceboolean✅Determina se o vinculo entre os produtos e as mídias devem ser forçadas
linksarray✅Lista de produtos e mídias que devem ser vinculadas
links.*.productIdinteger✅Id único do produto
links.*.productAttributeValueIdinteger❌Identificador do valor de atributo que deve ser vinculado
links.*.mediasarray✅Lista de ids de mídias que devem ser vinculadas
links..medias.integer✅Identificador da mídia que deve ser vinculada

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/medias/links \
3  --header "Authorization: Bearer userToken" \

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "productId": 67,
3  "productAttributeValueId": null,
4  "medias": [
5    2721, 
6    223
7  ]
8}

⚠️ 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_PRODUCT_NOT_FOUND404Os produtos solicitados (1, 2, 3) não foram encontrados.
UAPPI_STORE_PRODUCT_MEDIA_NOT_FOUND404As mídias de produto solicitadas (1, 2, 3) não foram encontradas.
UAPPI_STORE_ATTRIBUTE_VALUE_NOT_FOUND404Os valores de atributos solicitados (1, 2, 3) não foram encontrados.

Desvincular imagens de um produto

DELETE /products/medias/links

Possibilita que o lojista possa remover o vínculo entre mídias e produto

Descrição

Endpoint responsável por atualizar o vínculo das mídias de um produto 🔄.

Atua em contexto administrativo, permitindo que o lojista gerencie quais imagens, links ou documentos permanecem associados ao produto.

Por meio desse endpoint, é possível remover mídias que não devem mais estar vinculadas, ajustando a composição visual da página do produto.

Essa atualização possibilita refinar a galeria de mídias, removendo conteúdos desatualizados, incorretos ou que não representam mais o produto.

Dessa forma, o lojista consegue manter a apresentação do produto sempre alinhada e atualizada, garantindo uma melhor experiência para o cliente final ⚙️.

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
linksarray✅Lista de mídias e produtos que devem ser desvinculados
links.*.productIdinteger✅Identificador do produto que deve ser desvinculado da mídia
links.*.productAttributeValueIdinteger✅Identificador do valor de atributo que deve ser desvinculado
links.*.mediasarray✅Lista de ids de mídias que devem ser desvinculadas
links..medias.string✅Identificador da mídia de produto a ser desvinculada

Exemplo de Requisição

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

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "productId": 1,
3  "productAttributeValueId": null,
4  "medias": [
5    1
6  ]
7}

Alteração de ordenação de mídias de um produto

PUT /products/medias/links/order

Possibilita ao lojiosta reordernar as mídias do produto

Descrição

Este endpoint é responsável por atualizar a ordem das imagens vinculadas a um produto.

No corpo da requisição, deve ser informado o ID do produto e, caso exista, o ID do atributo do produto. As imagens só poderão ser reordenadas se já estiverem previamente vinculadas ao produto.

Os IDs das imagens devem ser enviados no corpo da requisição na ordem desejada, pois a sequência informada será aplicada como a nova ordem de exibição na página do produto.

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
productIdstring✅Id único do produto
productAttributeValueIdstring✅Id único do atributo do produto
mediasstring✅Id único da imagem que será vinculada

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/products/medias/links/order \
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "links": [
6      {
7        "productId": 1,
8        "productAttributeValueId": null,
9        "medias": [1]
10      }
11    ]
12  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "productId": 1,
3  "productAttributeValueId": null,
4  "medias": [
5    1,
6    2
7  ]
8}

Processamento de mídias de produto

POST /products/medias/process

Solicita o processamento assíncrono de mídias de produto em lote

Descrição

Endpoint responsável por receber uma lista de mídias de produto e solicitar o processamento assíncrono de cada item informado.

Use este endpoint quando o objetivo for processar um conjunto específico de mídias, informado por productMediaId no corpo da requisição.

O processamento é enfileirado e tratado em segundo plano. Por isso, o endpoint confirma o recebimento do lote (200 OK) e retorna o resultado item a item, sem bloquear a requisição até o fim da geração das derivadas.

O endpoint não falha o lote inteiro em caso de erro parcial. Cada item recebe seu próprio erro no campo error ou null em caso de sucesso.

Para saber mais sobre como as imagens derivadas serão geradas, consulte a sessão Otimização de imagens.

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
itemsarraySimLista de mídias para processamento (min:1, max:20)
items.*.productMediaIdintegerSimIdentificador da mídia de produto
forcebooleanNãoQuando true, ignora a validação de mídia já processada. Padrão: false

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/medias/process \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "items": [
7      {
8        "productMediaId": 101
9      },
10      {
11        "productMediaId": 102
12      }
13    ],
14    "force": true
15  }'

✅ Resposta de Sucesso

HTTP Status: 200 Accepted

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

⚠️ 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_PRODUCT_MEDIA_NOT_FOUND404A mídia informada não foi encontrada no contexto da loja.
UAPPI_STORE_PRODUCT_MEDIA_INVALID_TYPE400A mídia informada não é do tipo image.
UAPPI_STORE_PRODUCT_MEDIA_ALREADY_PROCESSED409A mídia já foi processada anteriormente. Pode ser ignorado por item com force: true.
UAPPI_STORE_PRODUCT_MEDIA_DUPLICATED_IN_PAYLOAD409O mesmo productMediaId foi enviado mais de uma vez no corpo da requisição.

Processamento forçado de todas as mídias de produto

POST /products/medias/process/all

Solicita o processamento assíncrono forçado de todas as mídias de imagem da loja

Descrição

Endpoint responsável por solicitar o reprocessamento de todas as mídias do tipo image da loja.

Use este endpoint para operações de reprocessamento em massa, quando for necessário regenerar as variações de imagem de toda a loja (por exemplo, após ajustes de configuração de otimização, revisão de arquivos derivados ou manutenção operacional).

A execução é assíncrona e em lote. O processamento completo pode levar mais tempo conforme a quantidade de mídias da loja aumenta.

O processamento é forçado, portanto, mídias com imageProcessed = 1 também entram no fluxo e podem ter suas derivadas recriadas.

Para saber mais sobre como as imagens derivadas serão geradas, consulte a sessão Otimização de imagens.

Parâmetros

Headers Obrigatórios

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

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/products/medias/process/all \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json"

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

⚠️ Possíveis erros:

Este endpoint não possui erros de domínio específicos.

Exclusão de uma mídia de produto

DELETE /products/medias

Exclusão de uma mídia de produto

Descrição

Endpoint responsável por permitir a exclusão de mídias associadas a produtos 🗑️.

Atua em contexto administrativo, possibilitando que o lojista remova imagens, links ou documentos vinculados aos produtos.

Por meio desse endpoint, é possível excluir mídias previamente associadas, permitindo ajustes ou correções na apresentação do produto.

Dessa forma, o lojista consegue manter a galeria de mídias organizada e atualizada, garantindo consistência na exibição das informações visuais ⚙️.

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
mediaIdsarray✅Lista de ids de mídias a serem excluídas
mediaIds.*integer✅Id da mídia que será excluída

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/products/medias \
3  --header "Authorization: Bearer userToken" \
4  --data '{
5    "mediaIds" [
6      1, 2, 3
7    ]
8  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

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

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

Institucional

;