API atual/Referência completa/Ferramentas do catálogo do seller

Anexos e imagens

Altera e apaga anexos de produto e apaga imagens de produto do seller.

Alterar um anexo

Atualiza o nome, a URL, o tipo e a descrição de um anexo de produto seu. Atenção: description e position são sempre regravados com o que você enviar; omiti-los os zera.

PUT/api/v1/vendor/attachments/{attachmentId}Seller

Alterar um anexo

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

attachmentIduuidobrigatório

Id do anexo.

Corpo da requisição

file_namestring

Novo nome. Vazio, não muda.

file_urlstring

Nova URL. Vazia, não muda.

file_sizeinteger

Novo tamanho em bytes. Zero, não muda.

mime_typestring

Novo tipo. Vazio, não muda.

descriptionstring

Descrição. Sempre regravada: omitida, vira vazia.

positioninteger

Ordem. Sempre regravada: omitida, vira 0.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/attachments/$ATTACHMENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "file_name": "manual-cafeteira-v2.pdf",
  "description": "Manual de instruções (versão 2)",
  "position": 1
}'

Resposta

200Anexo alterado

json

{
  "id": "5e8a1c3d-2b7f-4a90-9d64-0f1e2d3c4b5a",
  "product_id": "0c5a7e14-3b2d-4c19-8f66-7a1d2e3f4b50",
  "file_name": "manual-cafeteira.pdf",
  "file_url": "https://cdn.example.com/p/manual-cafeteira.pdf",
  "file_size": 482113,
  "mime_type": "application/pdf",
  "description": "Manual de instruções",
  "position": 1,
  "download_count": 12,
  "created_at": "2026-09-01T12:00:00Z",
  "updated_at": "2026-10-11T18:20:00Z"
}

Campos da resposta

iduuid

Id do anexo.

product_iduuid

Produto dono.

file_namestring

Nome do arquivo mostrado ao cliente.

file_urlstring

URL do arquivo.

file_sizeinteger

Tamanho em bytes.

mime_typestring

Tipo do arquivo, por exemplo application/pdf.

descriptionstring

Descrição curta.

positioninteger

Ordem entre os anexos do produto.

download_countinteger

Quantas vezes foi baixado.

created_atstring

RFC 3339.

updated_atstring

RFC 3339.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).	`{"error":"vendor_pending_review","message":"..."}`
403	O usuário tem papel de seller, mas não está ligado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário da equipe do seller não tem nenhum dos privilégios exigidos: `vendor_catalog`, `vendor_view_catalog`, `vendor_manage_products`, `vendor_manage_master`, `vendor_manage_mix`, `vendor_manage_quotes`, `vendor_manage_features`, `vendor_import_products`.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog","vendor_view_catalog","vendor_manage_products","vendor_manage_master","vendor_manage_mix","vendor_manage_quotes","vendor_manage_features","vendor_import_products"]}`
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
403	O anexo é de produto de outro seller.	`{"error":"you do not have access to this attachment"}`
404	Anexo inexistente.	`{"error":"attachment not found"}`
500	`attachmentId` que não é UUID, ou falha ao gravar.	`{"error":"failed to resolve attachment owner","detail":"..."}`

Apagar um anexo

Remove o anexo da página do produto. O arquivo continua existindo no armazenamento; só o registro do anexo é apagado.

DELETE/api/v1/vendor/attachments/{attachmentId}Seller

Apagar um anexo

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Parâmetros de caminho

attachmentIduuidobrigatório

Id do anexo.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/attachments/$ATTACHMENT_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Apagado

json

{
  "message": "attachment deleted"
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).	`{"error":"vendor_pending_review","message":"..."}`
403	O usuário tem papel de seller, mas não está ligado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário da equipe do seller não tem nenhum dos privilégios exigidos: `vendor_catalog`, `vendor_view_catalog`, `vendor_manage_products`, `vendor_manage_master`, `vendor_manage_mix`, `vendor_manage_quotes`, `vendor_manage_features`, `vendor_import_products`.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog","vendor_view_catalog","vendor_manage_products","vendor_manage_master","vendor_manage_mix","vendor_manage_quotes","vendor_manage_features","vendor_import_products"]}`
403	O anexo é de produto de outro seller.	`{"error":"you do not have access to this attachment"}`
404	Anexo inexistente.	`{"error":"attachment not found"}`
500	`attachmentId` que não é UUID, ou falha ao apagar.	`{"error":"failed to delete attachment","detail":"..."}`

Apagar uma imagem

Remove uma imagem da galeria de um produto seu. Confere que o produto é do seu seller antes de apagar.

DELETE/api/v1/vendor/images/{id}Seller

Apagar uma imagem de produto

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da imagem (o id que vem nas imagens do produto).

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/images/$IMAGE_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Apagada

json

{
  "message": "image deleted"
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).	`{"error":"vendor_pending_review","message":"..."}`
403	O usuário tem papel de seller, mas não está ligado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário da equipe do seller não tem nenhum dos privilégios exigidos: `vendor_catalog`, `vendor_view_catalog`, `vendor_manage_products`, `vendor_manage_master`, `vendor_manage_mix`, `vendor_manage_quotes`, `vendor_manage_features`, `vendor_import_products`.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog","vendor_view_catalog","vendor_manage_products","vendor_manage_master","vendor_manage_mix","vendor_manage_quotes","vendor_manage_features","vendor_import_products"]}`
403	A imagem é de produto de outro seller.	`{"error":"you do not have access to this image"}`
404	Imagem ou produto inexistente.	`{"error":"image not found"}`
500	Falha ao consultar ou apagar.	`{"error":"failed to delete image","detail":"..."}`

API atual/Referência completa/Ferramentas do catálogo do seller

Anexos e imagens

Altera e apaga anexos de produto e apaga imagens de produto do seller.

Alterar um anexo

Atualiza o nome, a URL, o tipo e a descrição de um anexo de produto seu. Atenção: description e position são sempre regravados com o que você enviar; omiti-los os zera.

PUT/api/v1/vendor/attachments/{attachmentId}Seller

Alterar um anexo

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

attachmentIduuidobrigatório

Id do anexo.

Corpo da requisição

file_namestring

Novo nome. Vazio, não muda.

file_urlstring

Nova URL. Vazia, não muda.

file_sizeinteger

Novo tamanho em bytes. Zero, não muda.

mime_typestring

Novo tipo. Vazio, não muda.

descriptionstring

Descrição. Sempre regravada: omitida, vira vazia.

positioninteger

Ordem. Sempre regravada: omitida, vira 0.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/attachments/$ATTACHMENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "file_name": "manual-cafeteira-v2.pdf",
  "description": "Manual de instruções (versão 2)",
  "position": 1
}'

Resposta

200Anexo alterado

json

{
  "id": "5e8a1c3d-2b7f-4a90-9d64-0f1e2d3c4b5a",
  "product_id": "0c5a7e14-3b2d-4c19-8f66-7a1d2e3f4b50",
  "file_name": "manual-cafeteira.pdf",
  "file_url": "https://cdn.example.com/p/manual-cafeteira.pdf",
  "file_size": 482113,
  "mime_type": "application/pdf",
  "description": "Manual de instruções",
  "position": 1,
  "download_count": 12,
  "created_at": "2026-09-01T12:00:00Z",
  "updated_at": "2026-10-11T18:20:00Z"
}

Campos da resposta

iduuid

Id do anexo.

product_iduuid

Produto dono.

file_namestring

Nome do arquivo mostrado ao cliente.

file_urlstring

URL do arquivo.

file_sizeinteger

Tamanho em bytes.

mime_typestring

Tipo do arquivo, por exemplo application/pdf.

descriptionstring

Descrição curta.

positioninteger

Ordem entre os anexos do produto.

download_countinteger

Quantas vezes foi baixado.

created_atstring

RFC 3339.

updated_atstring

RFC 3339.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).	`{"error":"vendor_pending_review","message":"..."}`
403	O usuário tem papel de seller, mas não está ligado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário da equipe do seller não tem nenhum dos privilégios exigidos: `vendor_catalog`, `vendor_view_catalog`, `vendor_manage_products`, `vendor_manage_master`, `vendor_manage_mix`, `vendor_manage_quotes`, `vendor_manage_features`, `vendor_import_products`.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog","vendor_view_catalog","vendor_manage_products","vendor_manage_master","vendor_manage_mix","vendor_manage_quotes","vendor_manage_features","vendor_import_products"]}`
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
403	O anexo é de produto de outro seller.	`{"error":"you do not have access to this attachment"}`
404	Anexo inexistente.	`{"error":"attachment not found"}`
500	`attachmentId` que não é UUID, ou falha ao gravar.	`{"error":"failed to resolve attachment owner","detail":"..."}`

Apagar um anexo

Remove o anexo da página do produto. O arquivo continua existindo no armazenamento; só o registro do anexo é apagado.

DELETE/api/v1/vendor/attachments/{attachmentId}Seller

Apagar um anexo

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Parâmetros de caminho

attachmentIduuidobrigatório

Id do anexo.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/attachments/$ATTACHMENT_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Apagado

json

{
  "message": "attachment deleted"
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).	`{"error":"vendor_pending_review","message":"..."}`
403	O usuário tem papel de seller, mas não está ligado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário da equipe do seller não tem nenhum dos privilégios exigidos: `vendor_catalog`, `vendor_view_catalog`, `vendor_manage_products`, `vendor_manage_master`, `vendor_manage_mix`, `vendor_manage_quotes`, `vendor_manage_features`, `vendor_import_products`.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog","vendor_view_catalog","vendor_manage_products","vendor_manage_master","vendor_manage_mix","vendor_manage_quotes","vendor_manage_features","vendor_import_products"]}`
403	O anexo é de produto de outro seller.	`{"error":"you do not have access to this attachment"}`
404	Anexo inexistente.	`{"error":"attachment not found"}`
500	`attachmentId` que não é UUID, ou falha ao apagar.	`{"error":"failed to delete attachment","detail":"..."}`

Apagar uma imagem

Remove uma imagem da galeria de um produto seu. Confere que o produto é do seu seller antes de apagar.

DELETE/api/v1/vendor/images/{id}Seller

Apagar uma imagem de produto

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Parâmetros de caminho

iduuidobrigatório

Id da imagem (o id que vem nas imagens do produto).

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/images/$IMAGE_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Apagada

json

{
  "message": "image deleted"
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).	`{"error":"vendor_pending_review","message":"..."}`
403	O usuário tem papel de seller, mas não está ligado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
403	O usuário da equipe do seller não tem nenhum dos privilégios exigidos: `vendor_catalog`, `vendor_view_catalog`, `vendor_manage_products`, `vendor_manage_master`, `vendor_manage_mix`, `vendor_manage_quotes`, `vendor_manage_features`, `vendor_import_products`.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog","vendor_view_catalog","vendor_manage_products","vendor_manage_master","vendor_manage_mix","vendor_manage_quotes","vendor_manage_features","vendor_import_products"]}`
403	A imagem é de produto de outro seller.	`{"error":"you do not have access to this image"}`
404	Imagem ou produto inexistente.	`{"error":"image not found"}`
500	Falha ao consultar ou apagar.	`{"error":"failed to delete image","detail":"..."}`