API atual/Referência completa/Produtos do seller

Importar e exportar CSV

Exporta os produtos do seller em CSV, baixa o modelo e importa produtos de CSV ou XLSX em uma chamada.

Estas três rotas cobrem o ciclo mais simples de carga em massa: baixe o modelo, preencha, envie. Todas operam só sobre os produtos do seu seller; qualquer vendor_id na planilha é trocado pelo seu.

Exportar

Baixa os seus produtos como arquivo CSV (separador ;, UTF-8 com BOM, preços em reais com ponto decimal, como 49.90). É a melhor forma de fazer um backup ou de ver o formato que a importação espera.

GET/api/v1/vendor/products/exportSeller

Exportar produtos em CSV

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de consulta

statusstring

Só produtos neste status (letra: A, D, H, R, X).

category_idstring (uuid)

Só desta categoria.

date_fromstring

Criados a partir desta data.

date_tostring

Criados até esta data.

Exemplo de requisição (exportar)

bash

curl "$BASE_URL/api/v1/vendor/products/export?status=A" \
  -H "Authorization: Bearer $TOKEN"

Resposta (exportar)

200Arquivo CSV

text

sku;name;slug;price;list_price;cost_price;quantity;min_quantity;max_quantity;quantity_step;status;category_id;vendor_id;description;short_description;promo_text;weight;length;width;height;free_shipping;shipping_freight;meta_title;meta_description;meta_keywords
CAM-001;Camiseta Básica Algodão Preta;camiseta-basica-algodao-preta;49.90;59.90;;25;0;0;1;A;345ac33e-4dcd-4d60-bedf-a2c2d47897d9;94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36;<p>Camiseta 100% algodão.</p>;Camiseta 100% algodão;;0.250;40.000;30.000;2.000;N;;;;

Campos da resposta

(cabeçalho)text/csv

Resposta com Content-Disposition: attachment; filename="produtos.csv". As 25 colunas são as mesmas aceitas na importação.

Erros (exportar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}`
500	Falha ao montar o arquivo (a resposta pode já ter começado).	`{"error":"export products failed","detail":"..."}`

Modelo de planilha

Devolve um CSV de exemplo com o cabeçalho mínimo e duas linhas de exemplo. Preencha e envie em Importar.

GET/api/v1/vendor/products/import/templateSeller

Baixar o modelo de planilha

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Exemplo de requisição (modelo)

bash

curl "$BASE_URL/api/v1/vendor/products/import/template" \
  -H "Authorization: Bearer $TOKEN"

Resposta (modelo)

200Modelo CSV

text

product_code;name;price;list_price;status;quantity;weight;category_id;vendor_id;description;short_description
SKU-001;Produto Exemplo 1;49,90;59,90;A;100;0,500;...;...;Descrição completa;Resumo curto

Campos da resposta

(cabeçalho)text/csv

Arquivo produtos_template.csv. A coluna product_code é aceita como sinônimo de sku.

Erros (modelo)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}`

Importar

Envia uma planilha e cria ou atualiza produtos na hora, numa só chamada. A chave de atualização é o SKU: linha com SKU que já existe vira atualização (se update_existing for true), as demais viram produtos novos. Para planilhas grandes, ou quando você precisa mapear colunas com nomes diferentes, use o assistente de importação.

POST/api/v1/vendor/products/importSeller

Importar produtos de CSV ou XLSX

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Corpo da requisição (multipart/form-data)

filefileobrigatório

Planilha .csv, .txt, .xml, .xlsx ou .xlsm. Em XLSX só a primeira aba é lida. Tamanho de formulário até 32 MB.

update_existingbooleanpadrão: true

false ignora linhas cujo SKU já existe.

skip_errorsbooleanpadrão: true

false para na primeira linha com erro; true continua e lista os erros.

Exemplo de requisição (importar)

bash

curl -X POST "$BASE_URL/api/v1/vendor/products/import" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@produtos.csv" \
  -F "update_existing=true"

Resposta (importar)

200Resumo da importação

json

{
  "total": 2,
  "created": 1,
  "imported": 1,
  "updated": 1,
  "skipped": 0,
  "errors": [],
  "warnings": []
}

Campos da resposta

totalinteger

Linhas de dados lidas.

createdinteger

Produtos criados.

importedinteger

Apelido antigo de created.

updatedinteger

Produtos atualizados.

skippedinteger

Linhas ignoradas por erro ou por update_existing: false.

errorsarray

Erros por linha: row (a linha 1 é o cabeçalho), field e message.

warningsarray

Linhas importadas, mas não exatamente como escritas (por exemplo, slug repetido que ganhou sufixo).

Erros (importar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}`
400	Falta o campo `file`, o formulário é inválido, a planilha está vazia ou falta a coluna `name` ou `price`.	`{"error":"missing_required_column","detail":"missing required column: price"}`
415	Extensão de arquivo não aceita.	`{"error":"unsupported file type","detail":"only CSV, XLSX and XML files are accepted (got \".pdf\")"}`

Veja também

API atual/Referência completa/Produtos do seller

Importar e exportar CSV

Exporta os produtos do seller em CSV, baixa o modelo e importa produtos de CSV ou XLSX em uma chamada.

Exportar

GET/api/v1/vendor/products/exportSeller

Exportar produtos em CSV

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de consulta

statusstring

Só produtos neste status (letra: A, D, H, R, X).

category_idstring (uuid)

Só desta categoria.

date_fromstring

Criados a partir desta data.

date_tostring

Criados até esta data.

Exemplo de requisição (exportar)

bash

curl "$BASE_URL/api/v1/vendor/products/export?status=A" \
  -H "Authorization: Bearer $TOKEN"

Resposta (exportar)

200Arquivo CSV

text

sku;name;slug;price;list_price;cost_price;quantity;min_quantity;max_quantity;quantity_step;status;category_id;vendor_id;description;short_description;promo_text;weight;length;width;height;free_shipping;shipping_freight;meta_title;meta_description;meta_keywords
CAM-001;Camiseta Básica Algodão Preta;camiseta-basica-algodao-preta;49.90;59.90;;25;0;0;1;A;345ac33e-4dcd-4d60-bedf-a2c2d47897d9;94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36;<p>Camiseta 100% algodão.</p>;Camiseta 100% algodão;;0.250;40.000;30.000;2.000;N;;;;

Campos da resposta

(cabeçalho)text/csv

Resposta com Content-Disposition: attachment; filename="produtos.csv". As 25 colunas são as mesmas aceitas na importação.

Erros (exportar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}`
500	Falha ao montar o arquivo (a resposta pode já ter começado).	`{"error":"export products failed","detail":"..."}`

Modelo de planilha

Devolve um CSV de exemplo com o cabeçalho mínimo e duas linhas de exemplo. Preencha e envie em Importar.

GET/api/v1/vendor/products/import/templateSeller

Baixar o modelo de planilha

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Exemplo de requisição (modelo)

bash

curl "$BASE_URL/api/v1/vendor/products/import/template" \
  -H "Authorization: Bearer $TOKEN"

Resposta (modelo)

200Modelo CSV

text

product_code;name;price;list_price;status;quantity;weight;category_id;vendor_id;description;short_description
SKU-001;Produto Exemplo 1;49,90;59,90;A;100;0,500;...;...;Descrição completa;Resumo curto

Campos da resposta

(cabeçalho)text/csv

Arquivo produtos_template.csv. A coluna product_code é aceita como sinônimo de sku.

Erros (modelo)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}`

Importar

POST/api/v1/vendor/products/importSeller

Importar produtos de CSV ou XLSX

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Corpo da requisição (multipart/form-data)

filefileobrigatório

Planilha .csv, .txt, .xml, .xlsx ou .xlsm. Em XLSX só a primeira aba é lida. Tamanho de formulário até 32 MB.

update_existingbooleanpadrão: true

false ignora linhas cujo SKU já existe.

skip_errorsbooleanpadrão: true

false para na primeira linha com erro; true continua e lista os erros.

Exemplo de requisição (importar)

bash

curl -X POST "$BASE_URL/api/v1/vendor/products/import" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@produtos.csv" \
  -F "update_existing=true"

Resposta (importar)

200Resumo da importação

json

{
  "total": 2,
  "created": 1,
  "imported": 1,
  "updated": 1,
  "skipped": 0,
  "errors": [],
  "warnings": []
}

Campos da resposta

totalinteger

Linhas de dados lidas.

createdinteger

Produtos criados.

importedinteger

Apelido antigo de created.

updatedinteger

Produtos atualizados.

skippedinteger

Linhas ignoradas por erro ou por update_existing: false.

errorsarray

Erros por linha: row (a linha 1 é o cabeçalho), field e message.

warningsarray

Linhas importadas, mas não exatamente como escritas (por exemplo, slug repetido que ganhou sufixo).

Erros (importar)

Status	Quando	Corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	Token que não é de seller, ou usuário sem o privilégio exigido pela rota.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_import_products"]}`
400	Falta o campo `file`, o formulário é inválido, a planilha está vazia ou falta a coluna `name` ou `price`.	`{"error":"missing_required_column","detail":"missing required column: price"}`
415	Extensão de arquivo não aceita.	`{"error":"unsupported file type","detail":"only CSV, XLSX and XML files are accepted (got \".pdf\")"}`