# Enviar foto de produto ou de estampa

> A loja baixa a imagem de uma URL pública e a liga a um produto (pelo código de barras de uma variação) ou a uma estampa. Processamento assíncrono.

Fonte: https://api.viashopmoda.com.br/docs-api/?p=recursos/imagens/upload · Atualizado em 16/11/2026


## O que faz

Você envia a **URL** de uma imagem; a loja valida o pedido, coloca o download numa fila e responde na hora. Em seguida a imagem é baixada, redimensionada e ligada:

- **foto de produto** (`produto`): ao produto e à estampa da variação do `cod_barras`;
- **imagem de estampa** (`estampa`): à estampa pelo nome; a estampa passa a ser do tipo imagem.

Uma requisição = uma imagem.

## Requisição

| | |
|---|---|
| **Método** | `POST` |
| **URL** | `https://api.viashopmoda.com.br/via/imagens/upload/{TOKEN}` |
| **Corpo** | Objeto JSON `{ ... }`, cabeçalho `Content-Type: application/json` |
| **Token** | Substitua `{TOKEN}` pelo token da loja. Ele vai no caminho da URL, não em cabeçalho. |
| **Processamento** | **Assíncrono.** A resposta confirma que a ação entrou na fila (`automacao_id`). Acompanhe com [`automacao/consultar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/automacao/consultar&formato=md). |


## Campos

Envie **um** dos objetos:

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `produto.cod_barras` | texto | **sim** | Código de barras de uma variação do produto. A foto fica ligada à estampa dessa variação. |
| `produto.arquivo` | texto | **sim** | URL pública e completa da imagem. |
| `estampa.nome` | texto | **sim** | Nome da estampa. |
| `estampa.arquivo` | texto | **sim** | URL pública e completa da imagem. |

## Regras

- A URL **não pode** ter espaços nem letras acentuadas ou caracteres como `ç`, `ã`, `<`, `>`. Codifique ou renomeie o arquivo.
- Formatos: JPEG, PNG ou WEBP.
- Foto de produto: tamanho ideal 900 × 1350 px. Imagens menores são aceitas, mas ganham bordas brancas.
- A loja guarda a URL de origem: enviar de novo a **mesma URL** para o mesmo produto é recusado (`Arquivo enviado já existe para o produto...`). Para trocar uma foto, use outra URL ou remova a antiga com [`imagens/remover`](https://api.viashopmoda.com.br/docs-api/?p=recursos/imagens/remover&formato=md).
- O `cod_barras` precisa existir e ser único.
- A ordem das fotos na loja segue a ordem de envio.

## Exemplo

```json
{
  "produto": {
    "cod_barras": "7890000000101",
    "arquivo": "https://seu-servidor.com.br/fotos/VES001-azul-1.jpg"
  }
}
```

```json
{
  "estampa": {
    "nome": "FLORAL ROSA",
    "arquivo": "https://seu-servidor.com.br/estampas/floral-rosa.png"
  }
}
```

## Respostas

Aceito (entrou na fila):

```json
{
  "retorno": true,
  "msg": "A automação 'produto.upload_foto' foi cadastrada e será processada.",
  "automacao_id": "123456",
  "consultar_automacao": "via/automacao/consultar/{TOKEN}?id=123456"
}
```

Acompanhe o resultado com [`automacao/consultar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/automacao/consultar&formato=md).

Recusas (na hora):

| Mensagem | Causa |
|---|---|
| `Caractere X inválido encontrado na posição N da url do arquivo.` | Acento ou caractere especial na URL. |
| `A url do arquivo não pode conter espaços` | Espaço na URL. |
| `produto não encontrado com o cod_barras:X.` | Código de barras inexistente. |
| `código de barras duplicado. cod_barras:X total:N.` | Mais de uma variação com o mesmo código. |
| `Arquivo enviado já existe para o produto. ...` | Essa URL já foi enviada para o produto (HTTP 200, `retorno: false`). |

## Pode reenviar?

A mesma URL para o mesmo produto é recusada com aviso — trate como "já enviada".

## Onde entra no processo

Guia [Catálogo](https://api.viashopmoda.com.br/docs-api/?p=guias/catalogo-carga-inicial&formato=md#3-enviar-as-fotos).
