VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Venddor Intelligence: ferramentas de IA

Importação de produtos por IA

Lê um arquivo de produtos (CSV, XLSX ou DOCX), simula e executa a criação e atualização em massa, e lista o histórico.

A importação tem dois passos separados. parse manda o arquivo e a VI interpreta as colunas, mesmo desorganizadas, devolvendo linhas de produto no formato da plataforma. run recebe essas linhas (que você pode corrigir antes) e cria ou atualiza os produtos. Entre um e outro, a interface mostra a tabela para o administrador conferir. O recurso é a chave enable_ai_bulk_product_import.

Regras da importação

  • A linha sem nome e sem SKU é ignorada (skipped).
  • Um SKU que já existe atualiza o produto: nome, descrição, preço e estoque são substituídos pelo que a linha traz, mesmo vazio ou zero. Categoria só muda se a linha informar uma.
  • Sem SKU existente, a linha cria um produto ativo; o nome é obrigatório. Sem categoria informada, o produto vai para uma categoria padrão.
  • Cada linha tem seu próprio resultado: uma linha com erro não impede as outras.
  • Com dry_run: true, nada é gravado nos produtos, mas a simulação fica registrada no histórico.

Ler o arquivo

Interpreta o arquivo e devolve as linhas de produto. Não grava nada na loja. Aceita .csv, .xlsx e .docx, até 10 MB.

POST/api/v1/admin/intelligence/import/parseAdmin

Ler um arquivo de produtos

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Corpo da requisição

filefileobrigatório
O arquivo, em multipart/form-data.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/intelligence/import/parse" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@produtos.xlsx"

Resposta

200Linhas lidas
json
{
  "format": "xlsx",
  "filename": "produtos.xlsx",
  "rows": [
    { "name": "Mouse Gamer Titan", "sku": "MG-01", "price_centavos": 12990, "stock": 40, "description": "Sensor óptico 16.000 DPI", "category_hint": "Periféricos" }
  ]
}

Campos da resposta

formatstring
csvxlsxdocx
Formato detectado pela extensão.
filenamestring
Nome recebido.
rowsarray
Linhas de produto.
rows[].namestring
Nome do produto. Obrigatório para criar.
rows[].skustring
SKU. É a chave de atualização.
rows[].price_centavosinteger
Preço em centavos. Negativo gera erro na linha.
rows[].stockinteger
Estoque.
rows[].descriptionstring
Descrição.
rows[].category_hintstring
Nome da categoria. Se existir na loja, é usada.
rows[].category_iduuid
Id da categoria. Vence category_hint.
rows[].image_url_hintstring
Endereço de uma imagem do produto, quando a planilha traz.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["manage_catalog","intelligence_use_bulk_import"]}
400Não é multipart, falta file, formato não suportado ou arquivo vazio.{"error":"file field missing"} ou {"error":"intelligence import: unsupported format (expected .csv, .xlsx, .docx)"}
403Importação por IA desligada.{"error":"AI bulk product import is disabled ..."}
413Arquivo acima de 10 MB.{"error":"intelligence import: file exceeds 10 MB cap"}
503Sem provedor de IA configurado.{"error":"no AI provider configured"}
Confira os preços

A VI converte preços e quantidades do arquivo para price_centavos e stock. Mostre as linhas ao administrador antes de chamar run: uma vírgula decimal mal lida vira um preço 100 vezes maior ou menor.

Importar ou simular

Cria ou atualiza os produtos das linhas enviadas. A chamada é síncrona e só volta quando todas as linhas foram processadas.

POST/api/v1/admin/intelligence/import/runAdmin

Importar ou simular

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

rowsarrayobrigatório
Linhas de produto, no formato devolvido por parse (campos abaixo). Não pode estar vazio.
dry_runbooleanpadrão: false
true simula: cada linha informa o que aconteceria, sem gravar produtos.
filenamestring
Nome do arquivo de origem, para o histórico.
formatstring
Formato de origem, para o histórico.
rows[].namestring
Nome do produto. Obrigatório para criar.
rows[].skustring
SKU. É a chave de atualização.
rows[].price_centavosinteger
Preço em centavos. Negativo gera erro na linha.
rows[].stockinteger
Estoque.
rows[].descriptionstring
Descrição.
rows[].category_hintstring
Nome da categoria. Se existir na loja, é usada.
rows[].category_iduuid
Id da categoria. Vence category_hint.
rows[].image_url_hintstring
Endereço de uma imagem do produto, quando a planilha traz.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/intelligence/import/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dry_run": true,
    "filename": "produtos.xlsx",
    "format": "xlsx",
    "rows": [
      {
        "name": "Mouse Gamer Titan",
        "sku": "MG-01",
        "price_centavos": 12990,
        "stock": 40,
        "description": "Sensor óptico 16.000 DPI",
        "category_hint": "Periféricos"
      }
    ]
  }'

Resposta

200Resultado
json
{
  "run_id": "bcf4c219-1811-4402-8c3c-a8564ca50361",
  "dry_run": true,
  "total_rows": 1,
  "created_count": 1,
  "updated_count": 0,
  "skipped_count": 0,
  "errored_count": 0,
  "rows": [
    {
      "row": { "name": "Produto Teste", "sku": "DOCS-PROBE-1", "price_centavos": 1990, "stock": 3, "description": "" },
      "status": "created",
      "message": "dry-run: would create"
    }
  ]
}

Campos da resposta

run_iduuid
Id do registro no histórico.
dry_runboolean
Se foi simulação.
total_rowsinteger
Linhas recebidas.
created_countinteger
Linhas que criaram (ou criariam) produto.
updated_countinteger
Linhas que atualizaram (ou atualizariam).
skipped_countinteger
Linhas ignoradas.
errored_countinteger
Linhas com erro.
rows[].rowobject
A linha enviada.
rows[].statusstring
createdupdatedskippederrored
Resultado da linha.
rows[].product_iduuid
Produto criado ou atualizado. Ausente em simulação de criação e em erros.
rows[].messagestring
Explicação (por exemplo missing both name and SKU, dry-run: would update). Em inglês.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["manage_catalog","intelligence_use_bulk_import"]}
400Corpo ilegível ou rows vazio.{"error":"rows array is empty"}
403Importação por IA desligada.{"error":"AI bulk product import is disabled ..."}
503Catálogo indisponível para a importação.{"error":"catalog adapter not configured"}
Atualização sobrescreve

Se o SKU já existe, nome, descrição, preço e estoque do produto passam a ser os da linha. Uma linha sem descrição apaga a descrição atual e uma sem estoque zera o estoque. Simule primeiro e compare com o catálogo.

Histórico

Lista as importações e simulações feitas por quem chama, da mais recente para a mais antiga, com o resultado de cada linha.

GET/api/v1/admin/intelligence/import/runsAdmin

Histórico de importações

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Parâmetros de consulta

limitintegerpadrão: 20
Quantidade. Padrão 20.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/intelligence/import/runs?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Execuções
json
{
  "runs": [
    {
      "id": "bcf4c219-1811-4402-8c3c-a8564ca50361",
      "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "filename": "produtos.xlsx",
      "format": "xlsx",
      "total_rows": 1,
      "created_count": 1,
      "updated_count": 0,
      "skipped_count": 0,
      "errored_count": 0,
      "rows": [],
      "created_at": "2026-10-11T21:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

runs[].iduuid
Id da execução.
runs[].filenamestring
Arquivo de origem.
runs[].formatstring
Formato.
runs[].total_rowsinteger
Linhas.
runs[].created_countinteger
Criadas.
runs[].updated_countinteger
Atualizadas.
runs[].skipped_countinteger
Ignoradas.
runs[].errored_countinteger
Com erro.
runs[].rowsarray
Resultado de cada linha, como em run.
runs[].created_atstring
RFC 3339.
totalinteger
Quantidade devolvida.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O administrador não tem nenhum dos privilégios exigidos.{"error":"insufficient privileges","privilege_required_any":["manage_catalog","intelligence_use_bulk_import"]}

Veja também

  • Visão geral
Anterior
Promoções por IA
Próxima
Perguntas sugeridas
Nesta página
  • Regras da importação
  • Ler o arquivo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Importar ou simular
  • Exemplo de requisição
  • Resposta
  • Erros
  • Histórico
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também