Referência da API

Upload de imagem do produto

Faz upload da imagem do produto via **multipart/form-data**. O arquivo é redimensionado (1024px de largura máxima) e convertido pra WebP no servidor antes de ser hospedado no nosso S3. Use esse endpoint pra **adicionar** ou **substituir** a imagem. Se já havia imagem, ela é sobrescrita (não duplica). A chave de API precisa da permissão `isInvoiceAvailable`.

POST/v2/products/:id/image

Limites estritos

file Aceita apenas JPG, PNG e WebP. Máximo 5MB. Acima do limite ou formato inválido retorna 400. Imagem corrompida (Sharp falha ao processar) também retorna 400.

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

idstring (path, UUID)obrigatório

UUID do produto.

Exemplo: prd_111aaa-bbb-ccc

filebinary (multipart)obrigatório

Arquivo de imagem. Aceita JPG, PNG ou WebP. Tamanho máximo: 5MB. Será processado: rotacionado conforme EXIF, redimensionado pra 1024px de largura máxima (mantendo aspect ratio), convertido pra WebP qualidade 85.

Exemplo: capa.jpg

Body da requisição

Content-Type: multipart/form-data

JSON

# Field obrigatório:
#   file — o arquivo de imagem
#
# Exemplo via cURL:
curl -X POST "https://api.pagnovo.com/v2/products/prd_111aaa-bbb-ccc/image" \
  -H "Authorization: Basic ..." \
  -F "file=@/caminho/local/capa.jpg"

Respostas

201

Imagem processada e salva. Retorna o Produto completo com imageUrl apontando pra URL pública no nosso S3.

JSON

{
  "id": "prd_111aaa-bbb-ccc",
  "name": "Curso de Marketing Digital",
  "description": "Curso completo",
  "imageUrl": "https://seu-bucket.s3.us-east-1.amazonaws.com/products/u-1234/prd_111aaa-bbb-ccc.webp",
  "externalId": "curso-mkt-2026",
  "active": true,
  "createdAt": "2026-05-26T14:32:01.923Z",
  "updatedAt": "2026-05-26T15:00:00.000Z"
}

400

Causas: arquivo ausente, MIME não suportado, tamanho > 5MB, imagem corrompida, produto arquivado.

JSON

{
  "status": 400,
  "error": "Formato nao suportado: image/gif. Aceitos: image/jpeg, image/png, image/webp"
}

404

Produto não encontrado.

JSON

{ "status": 404, "error": "Produto nao encontrado" }

Exemplos

cURL

curl -X POST "https://api.pagnovo.com/v2/products/prd_111aaa-bbb-ccc/image" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -F "file=@/caminho/local/capa.jpg"

JavaScript

// Browser/Node 18+ (FormData nativo)
const token = Buffer.from("secret:" + process.env.PAGNOVO_SECRET_KEY).toString("base64");

const fd = new FormData();
fd.append("file", fileBlob, "capa.jpg");

const res = await fetch("https://api.pagnovo.com/v2/products/prd_111aaa-bbb-ccc/image", {
  method: "POST",
  headers: { Authorization: `Basic ${token}` },
  body: fd,
});

const product = await res.json();
console.log("Nova URL:", product.imageUrl);