Imagens e mídias

Imagens não vão no JSON do produto — são enviadas depois, referenciando o SKU pelo seu externalReference. Há dois caminhos: API para volumes pequenos e correções pontuais, SFTP para carga inicial e lotes grandes.

Enviar por API


POST /v1/Storages/image/upload?externalReference={ref}

Corpo em multipart/form-data.

curl


curl -X POST \
  "$GROCERS_API/v1/Storages/image/upload?externalReference=114970" \
  -H "Authorization: Basic $BASIC" \
  -H "x-contractAccountId: $TENANT" \
  -F "files=@frente.jpg" \
  -F "files=@verso.jpg" \
  -F "orders=1" \
  -F "orders=2"

Parâmetro	Onde	Descrição
`externalReference`	query string	SKU que recebe as imagens
`files`	form-data	uma ou mais imagens no mesmo envio
`orders`	form-data	ordem de exibição, na mesma sequência de `files`

Resposta: 200 com { "operationId": "..." }.

O orders define qual imagem é a principal (1). Sem ele, a ordem segue a sequência de upload — que costuma variar entre execuções quando o envio é paralelo.

O corpo é limitado a 100 MB por requisição na plataforma (pode ser alterado conforme a necessidade do cliente).

Enviar por SFTP

Para carga inicial de catálogo, o caminho é subir os arquivos por SFTP e depois registrá-los pela API.

Conectar

Use um cliente SFTP (FileZilla, WinSCP, sftp de linha de comando) com as credenciais recebidas — host, porta 22, usuário e senha.

Navegar até a pasta correta

A estrutura de diretórios segue este caminho:


/<pasta-do-contrato>/<contractAccountId>/SKUs/Integracao

Normalmente só existe uma pasta com o seu contractAccountId no nome.

Subir os arquivos

Transfira as imagens para SKUs/Integracao. Nomeie de forma padronizada antes de subir — por exemplo 114970-frente.png, 114970-verso.png — porque é por esse nome que você vai referenciá-las depois.

Registrar via API

O upload por SFTP coloca o arquivo no servidor, mas não associa a imagem ao SKU. Chame POST /v1/Storages/image/upload para fazer o vínculo.

Parar no passo 3 é o erro clássico: os arquivos estão no servidor, ninguém vê erro nenhum, e as imagens não aparecem na vitrine porque não houve o registro do passo 4.

Consultar imagens de um SKU


GET /v1/Storages/file/{externalReference}/{fileType}

fileType é o tipo de entidade:

Valor	Entidade
`1`	SKU
`2`	Categoria
`3`	Badge
`4`	Nota fiscal
`5`	Produto


curl "$GROCERS_API/v1/Storages/file/114970/1" \
  -H "Authorization: Basic $BASIC" \
  -H "x-contractAccountId: $TENANT"


[
  "https://storage.blob.core.windows.net/.../SKUs/114970/frente.jpeg",
  "https://storage.blob.core.windows.net/.../SKUs/114970/verso.png"
]

Remover imagens


DELETE /v1/Storages/file/{externalReference}


{
  "fileType": 1,
  "urls": ["https://storage.blob.core.windows.net/.../frente.jpeg"],
  "storageIds": []
}

Campo	Obrigatório	Descrição
`fileType`	sim	Tipo da entidade (tabela acima)
`urls`	não	URLs específicas a remover
`storageIds`	não	IDs dos arquivos armazenados

Informe urls ou storageIds. Para remover todos os arquivos de uma entidade, use DELETE /v1/Storages/delete/{entityId}.

Existe ainda DELETE /v1/Storages/image/upload, que remove imagens pelo mesmo contrato do upload — útil para desfazer um envio recém-feito.

Nota fiscal do pedido

O mesmo serviço guarda o PDF da nota, com rotas próprias. Só PDF é aceito — o Content-Type precisa ser application/pdf, e o XML da NF-e é recusado com 400:


# anexar a nota ao pedido
curl -X POST \
  "$GROCERS_API/v1/Storages/invoice/upload?orderId=$ORDER_ID" \
  -H "Authorization: Basic $BASIC" \
  -H "x-contractAccountId: $TENANT" \
  -F "files=@nfe-12345.pdf"
 
# recuperar a nota anexada
curl "$GROCERS_API/v1/Storages/invoice?orderId=$ORDER_ID" \
  -H "Authorization: Basic $BASIC" \
  -H "x-contractAccountId: $TENANT"

A nota usa orderId (GUID interno do pedido), não o orderNumber que aparece para o cliente. O GUID vem no payload do webhook de pedido, campo id.

Order_InvoiceUploaded (32) é o nome interno dessa chamada, não uma notificação: o upload bem-sucedido não gera evento, e a recusa do core chega como Operation_Failed (999). Veja Faturamento.