Ferramentas do catálogo do seller

Esta seção reúne as rotas de apoio que o painel do seller (lojista) usa ao redor do cadastro de produtos: arquivos anexos (manual, ficha técnica), exclusão de imagens, as características que descrevem os produtos (cor, tamanho, marca), a lista de campos que o importador de planilhas aceita, as perguntas dos clientes na página do produto e o acompanhamento de tarefas em lote.

O cadastro em si (criar, alterar e listar produtos) é outra área: aqui está o que gira em torno dele.

Como funciona

1. Descreva o produto
   Leia GET /features e GET /features/{id}/variants para saber que características e valores existem (por exemplo Cor: Azul, Verde).
2. Gerencie arquivos
   Altere ou apague um anexo (PUT/DELETE /attachments/{attachmentId}) e apague imagens (DELETE /images/{id}).
3. Importe em massa
   Use GET /import-export/fields/{entity} para saber que colunas o importador entende e monte o mapeamento.
4. Responda os clientes
   GET /product-questions lista as perguntas dos seus produtos; PUT /product-questions/{id}/answer responde.
5. Acompanhe lotes
   Quando uma operação em lote vira tarefa, siga o progresso em GET /bulk-jobs/{id} ou /stream.

Conceitos-chave

Característica e variante

Uma característica (feature) é um atributo de produto: Cor, Material, Marca. As características do tipo lista têm variantes, os valores permitidos (Cor: Azul, Verde). A plataforma usa os tipos select, multi_select, brand, author e color com variantes, e text, number, date e bool com valor livre. group agrupa outras características.

Anexo

Um anexo é um arquivo ligado ao produto (manual em PDF, ficha técnica) que o cliente baixa na página do produto. O arquivo em si é guardado com o upload de mídia; o anexo guarda a URL e os dados.

Pergunta de cliente

Qualquer visitante pode perguntar na página do produto. A pergunta nasce pending. Ao ser respondida vira answered e passa a ser pública. O administrador pode rejectar (moderar) ou archivear.

Tarefa em lote

Operações em lote (como clonar muitos mestres) viram tarefa quando alcançam 50 registros ou mais. A tarefa tem estado queued, running, done, failed ou interrupted e contadores de progresso.

Endpoints

Erros comuns

• Esquecer que PUT /attachments regrava a posição e a descrição. Campos omitidos como position e description voltam a 0 e vazio. Mande-os sempre.
• Tentar criar característica por aqui. O seller só lê; a criação é do administrador.
• Passar page esperando paginar a lista padrão de características. A paginação vale para cada tipo separadamente (veja a página).
• Responder duas vezes uma pergunta. A segunda chamada não sobrescreve: devolve a pergunta como está.
• Acompanhar tarefa de outra pessoa. A tarefa só é visível a quem a iniciou; outro usuário recebe 404.
• Usar EventSource do navegador no stream. Ele não envia o cabeçalho Authorization. Use fetch e leia o corpo em partes.

Próximos passos