Importar itens de uma planilha

Baixa a planilha modelo e lê uma planilha de SKUs e quantidades, devolvendo o que foi encontrado no catálogo para enviar ao carrinho.

Compradores B2B costumam ter o pedido pronto numa planilha: código do produto e quantidade, centenas de linhas. Estas duas rotas permitem importar essa planilha: uma entrega o arquivo modelo e a outra lê o arquivo preenchido e diz, linha a linha, o que existe no catálogo.

O fluxo tem duas etapas e a rota de leitura não coloca nada no carrinho:

Baixar o modelo
Ofereça GET /bulk-cart/template ao comprador. É um CSV de duas colunas, com três linhas de exemplo.
Ler a planilha preenchida
Envie o arquivo para POST /bulk-cart/parse. A resposta separa matched (produtos encontrados, com preço e estoque) de unmatched (códigos que não existem ou não podem ser vendidos, com sugestões).
Enviar ao carrinho
Mostre o resultado ao comprador para conferir e então envie os itens de matched para Adicionar vários itens (POST /cart/bulk).

As duas rotas exigem o módulo de pedido por planilha ligado na loja; sem ele a resposta é 403 module_disabled. Não pedem login.

Baixar a planilha modelo

GET/api/v1/storefront/bulk-cart/templatePública

Baixa o modelo CSV de pedidos em lote

Devolve um arquivo CSV (text/csv, anexo bulk-order-template.csv) em UTF-8 com BOM, para o Excel abrir com acentos. O conteúdo padrão é o cabeçalho SKU,Quantity e três linhas de exemplo. Algumas lojas trocam o modelo (por exemplo, colunas Código;Quantidade separadas por ponto e vírgula), então baixe sempre o arquivo da loja em vez de copiar um modelo fixo.

bash

curl "$BASE_URL/api/v1/storefront/bulk-cart/template"

200CSV modelo

text

SKU,Quantity
PROD-001,5
PROD-002,10
PROD-003,1

Ler uma planilha

POST/api/v1/storefront/bulk-cart/parsePública

Interpreta uma planilha de SKUs e quantidades

Envie o arquivo como multipart/form-data, no campo file. São aceitos CSV, XLSX e XLS (no Excel, só a primeira aba é lida). O separador do CSV é detectado sozinho: vírgula, ponto e vírgula (Excel em português) ou tabulação.

A primeira linha precisa ser o cabeçalho. A coluna de código pode se chamar sku, product_code, codigo, código, code, ean, gtin, barcode, codigo_barras, código_barras ou cod; a de quantidade, quantity, qty, quantidade ou qtd (maiúsculas não importam). Se a planilha tem as duas colunas trocadas de lugar nos dados (quantidade no lugar do código e um EAN no lugar da quantidade), a API troca de volta.

Como cada linha é lida:

Só as 200 primeiras linhas de dados são lidas; o resto é ignorado em silêncio.
Códigos repetidos são juntados e as quantidades somadas.
Quantidade vazia, zero, negativa ou que não é número inteiro vira 1.
O código casa com o SKU do produto (sem diferenciar maiúsculas), com o EAN ou com o SKU de uma variação. Códigos numéricos de 8 dígitos ou mais casam também ignorando zeros à esquerda e pontuação.
Só entram em matched produtos ativos, com seller e visíveis para este comprador. Produto restrito a um grupo de clientes de que o comprador não faz parte aparece como not_found, para não revelar que existe.

Cabeçalhos

Authorizationstring

Opcional. Com Bearer <token>, a visibilidade por grupo de clientes é conferida para o cliente.

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

filefileobrigatório

A planilha. Tamanho máximo de 2 MB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/bulk-cart/parse" \
  -F "file=@pedido.csv"

Resposta

200Resultado da leitura

json

{
  "matched": [
    {
      "sku": "SD-002373",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "product_name": "Notebook Slim Rosa 02373",
      "price": 11500,
      "image_url": "/uploads/.../notebook.png",
      "quantity": 3,
      "in_stock": true,
      "available_qty": 51
    }
  ],
  "unmatched": [
    {
      "sku": "XXX-1",
      "quantity": 2,
      "reason": "not_found",
      "suggestions": []
    }
  ]
}

Campos da resposta

matchedarray

Produtos encontrados, na ordem da planilha.

matched[].skustring

O código como veio da planilha, em maiúsculas.

matched[].product_iduuid

Produto. Envie este valor em product_id ao adicionar ao carrinho.

matched[].product_namestring

Nome do produto.

matched[].unified_variation_idinteger

Presente quando o código é de uma variação unificada. Envie junto ao adicionar.

matched[].variation_iduuid

Presente quando o código é de uma variação do produto. Envie junto ao adicionar.

matched[].variation_labelstring

Texto da variação, como Tamanho: M.

matched[].priceinteger

Preço do catálogo em centavos. Não inclui preço B2B nem promoções; o preço final vem do carrinho.

matched[].image_urlstring

Imagem do produto.

matched[].quantityinteger

Quantidade pedida (já somada nas repetições).

matched[].in_stockboolean

false apenas quando o produto controla estoque e não há nenhuma unidade. Com estoque parcial continua true: compare quantity com available_qty para saber se a quantidade pedida cabe.

matched[].available_qtyinteger

Estoque cadastrado do produto (inteiro).

unmatchedarray

Códigos que não puderam ser usados.

unmatched[].skustring

O código da planilha.

unmatched[].quantityinteger

Quantidade pedida.

unmatched[].reasonstring

not_foundnot_sellable

not_found: nenhum produto com esse código (ou ele não é visível para o comprador). not_sellable: o produto existe mas não tem seller, então não pode ser comprado.

unmatched[].suggestionsarray

Produtos parecidos, para o comprador corrigir o código. Cada item tem product_id, product_name, sku e similarity (0 a 100). Vazio quando nada é parecido.

Erros

Status	Quando	Corpo
400	Arquivo maior que 2 MB ou formulário inválido	`{"error":"file too large or invalid form","detail":"maximum 2MB CSV file allowed"}`
400	Campo `file` ausente	`{"error":"file is required","detail":"upload a CSV file with 'file' field"}`
400	Arquivo ilegível ou planilha corrompida	`{"error":"invalid spreadsheet","detail":"..."}`
400	Só cabeçalho, sem linhas de dados	`{"error":"CSV must have a header row and at least one data row"}`
400	Sem coluna de código	`{"error":"CSV must have a SKU column","detail":"expected column header: SKU, product_code, codigo, or code"}`
400	Sem coluna de quantidade	`{"error":"CSV must have a Quantity column","detail":"expected column header: Quantity, qty, quantidade, or qtd"}`
400	Nenhuma linha utilizável	`{"error":"no valid rows found in CSV"}`
403	Módulo desligado	`{"error":"module_disabled","module":"bulk-cart"}`

Veja também

Importar itens de uma planilha

Baixa a planilha modelo e lê uma planilha de SKUs e quantidades, devolvendo o que foi encontrado no catálogo para enviar ao carrinho.

O fluxo tem duas etapas e a rota de leitura não coloca nada no carrinho:

Baixar o modelo
Ofereça GET /bulk-cart/template ao comprador. É um CSV de duas colunas, com três linhas de exemplo.
Ler a planilha preenchida
Envie o arquivo para POST /bulk-cart/parse. A resposta separa matched (produtos encontrados, com preço e estoque) de unmatched (códigos que não existem ou não podem ser vendidos, com sugestões).
Enviar ao carrinho
Mostre o resultado ao comprador para conferir e então envie os itens de matched para Adicionar vários itens (POST /cart/bulk).

As duas rotas exigem o módulo de pedido por planilha ligado na loja; sem ele a resposta é 403 module_disabled. Não pedem login.

Baixar a planilha modelo

GET/api/v1/storefront/bulk-cart/templatePública

Baixa o modelo CSV de pedidos em lote

bash

curl "$BASE_URL/api/v1/storefront/bulk-cart/template"

200CSV modelo

text

SKU,Quantity
PROD-001,5
PROD-002,10
PROD-003,1

Ler uma planilha

POST/api/v1/storefront/bulk-cart/parsePública

Interpreta uma planilha de SKUs e quantidades

Como cada linha é lida:

Só as 200 primeiras linhas de dados são lidas; o resto é ignorado em silêncio.
Códigos repetidos são juntados e as quantidades somadas.
Quantidade vazia, zero, negativa ou que não é número inteiro vira 1.
O código casa com o SKU do produto (sem diferenciar maiúsculas), com o EAN ou com o SKU de uma variação. Códigos numéricos de 8 dígitos ou mais casam também ignorando zeros à esquerda e pontuação.
Só entram em matched produtos ativos, com seller e visíveis para este comprador. Produto restrito a um grupo de clientes de que o comprador não faz parte aparece como not_found, para não revelar que existe.

Cabeçalhos

Authorizationstring

Opcional. Com Bearer <token>, a visibilidade por grupo de clientes é conferida para o cliente.

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

filefileobrigatório

A planilha. Tamanho máximo de 2 MB.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/bulk-cart/parse" \
  -F "file=@pedido.csv"

Resposta

200Resultado da leitura

json

{
  "matched": [
    {
      "sku": "SD-002373",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "product_name": "Notebook Slim Rosa 02373",
      "price": 11500,
      "image_url": "/uploads/.../notebook.png",
      "quantity": 3,
      "in_stock": true,
      "available_qty": 51
    }
  ],
  "unmatched": [
    {
      "sku": "XXX-1",
      "quantity": 2,
      "reason": "not_found",
      "suggestions": []
    }
  ]
}

Campos da resposta

matchedarray

Produtos encontrados, na ordem da planilha.

matched[].skustring

O código como veio da planilha, em maiúsculas.

matched[].product_iduuid

Produto. Envie este valor em product_id ao adicionar ao carrinho.

matched[].product_namestring

Nome do produto.

matched[].unified_variation_idinteger

Presente quando o código é de uma variação unificada. Envie junto ao adicionar.

matched[].variation_iduuid

Presente quando o código é de uma variação do produto. Envie junto ao adicionar.

matched[].variation_labelstring

Texto da variação, como Tamanho: M.

matched[].priceinteger

Preço do catálogo em centavos. Não inclui preço B2B nem promoções; o preço final vem do carrinho.

matched[].image_urlstring

Imagem do produto.

matched[].quantityinteger

Quantidade pedida (já somada nas repetições).

matched[].in_stockboolean

false apenas quando o produto controla estoque e não há nenhuma unidade. Com estoque parcial continua true: compare quantity com available_qty para saber se a quantidade pedida cabe.

matched[].available_qtyinteger

Estoque cadastrado do produto (inteiro).

unmatchedarray

Códigos que não puderam ser usados.

unmatched[].skustring

O código da planilha.

unmatched[].quantityinteger

Quantidade pedida.

unmatched[].reasonstring

not_foundnot_sellable

not_found: nenhum produto com esse código (ou ele não é visível para o comprador). not_sellable: o produto existe mas não tem seller, então não pode ser comprado.

unmatched[].suggestionsarray

Produtos parecidos, para o comprador corrigir o código. Cada item tem product_id, product_name, sku e similarity (0 a 100). Vazio quando nada é parecido.

Erros

Status	Quando	Corpo
400	Arquivo maior que 2 MB ou formulário inválido	`{"error":"file too large or invalid form","detail":"maximum 2MB CSV file allowed"}`
400	Campo `file` ausente	`{"error":"file is required","detail":"upload a CSV file with 'file' field"}`
400	Arquivo ilegível ou planilha corrompida	`{"error":"invalid spreadsheet","detail":"..."}`
400	Só cabeçalho, sem linhas de dados	`{"error":"CSV must have a header row and at least one data row"}`
400	Sem coluna de código	`{"error":"CSV must have a SKU column","detail":"expected column header: SKU, product_code, codigo, or code"}`
400	Sem coluna de quantidade	`{"error":"CSV must have a Quantity column","detail":"expected column header: Quantity, qty, quantidade, or qtd"}`
400	Nenhuma linha utilizável	`{"error":"no valid rows found in CSV"}`
403	Módulo desligado	`{"error":"module_disabled","module":"bulk-cart"}`