KernosDevelopers
Sair
Referência Pedidos de venda › Importar
Pedidos de venda › Importar

Cria um pedido de venda aberto, com a reserva feita

POST/v1/objects/sales-order

Duas formas, o mesmo pedido. Com csv, é a planilha de alguém: falta de saldo recusa o pedido inteiro. Com lines, é um sistema (o ERP ou o programa do cliente): o pedido entra mesmo com falta, e cada linha diz quanto faltou em shortage. Sem depot_code, vale o CD ativo mais antigo.

Ação da chave: sales_order.import

Quem cria a chave escolhe as ações que ela abre; sem esta, a rota recusa com api_key_action_not_granted.

Toda escrita pede Idempotency-Key

Um UUID por escrita. Repetida com o mesmo corpo, devolve a mesma resposta sem escrever de novo. Os SDKs mandam sozinhos.

Corpo

Mande uma destas formas:

Planilha

csv string OBRIGATÓRIO

Um pedido por arquivo, cabeçalho order_ref;customer;product;qty;carrier_cnpj. O produto é o EAN ou o SKU.

depot_code string

O código do CD. Sem ele, o CD ativo mais antigo.

Sistema

carrier_cnpj string

O CNPJ da transportadora, com 14 dígitos.

channel string

O canal da venda, pelo código do catálogo (shopee, mercado_livre…).

channel_ref string

O número do pedido no canal.

customer string
customer_area string

O bairro da entrega.

depot_code string

O código do CD. Sem ele, o CD ativo mais antigo.

lines lista de objeto OBRIGATÓRIO
3 campos
product string OBRIGATÓRIO

O EAN ou o SKU do produto.

qty integer OBRIGATÓRIO
unit_price number
order_ref string OBRIGATÓRIO

O número do pedido no sistema de origem. Repetido, recusa com order_already_imported.

origin string

O parceiro que manda o pedido (bling, tiny, shopify…). Sem ele, custom_api.

paid_note string

A frase do pagamento, como o canal escreveu.

Devolve

O data do envelope { ok, data, error, error_code, field, trace_id }:

sales_order objeto OBRIGATÓRIO
16 campos
carrier_cnpj string, ou nulo
channel string, ou nulo
channel_ref string, ou nulo
customer string, ou nulo
customer_area string, ou nulo
id uuid
lines integer

Quantas linhas o pedido tem.

minted integer

1 quando o código curto do pedido foi criado.

order_ref string
origin string

orders_csv para a planilha; o parceiro, ou custom_api, para o sistema.

outcome "ok"
paid_note string, ou nulo
short_units integer

Quantas unidades entraram sem saldo (só no pedido de sistema).

shortage lista de objeto
4 campos
product_id uuid
qty integer
seq integer
short_qty integer
status "open"
units integer

Quantas unidades, somadas.

Recusas

HTTP 400 · Pedido mal formado

invalid_idempotency_key HTTP 400Toda escrita pede o cabeçalho Idempotency-Key com um UUID.
version_unknown HTTP 400A Kernos-Version pedida não existe. Use uma das versões declaradas no cabeçalho, ou não o mande.

HTTP 401 · Sem credencial válida

api_key_expired HTTP 401A chave venceu. Gire a chave no painel e use a nova.
api_key_wrong_environment HTTP 401A chave é do outro ambiente: ksk_test_ vai em https://stag.kernos.com.br, ksk_live_ em https://api.kernos.com.br.
unauthenticated HTTP 401Credencial ausente, inválida ou expirada.

HTTP 403 · Sem permissão

agent_token_out_of_scope HTTP 403O token de agente (kat_) só vale na porta MCP. Para a API, use o token de sessão ou uma chave de integração.
api_key_action_not_granted HTTP 403A chave não tem esta ação. Edite as ações da chave no painel.
api_key_out_of_scope HTTP 403A chave só vale nas rotas do contrato público.
depot_out_of_reach HTTP 403Quem chama não alcança o CD deste objeto. Peça alcance ao CD ou use outra credencial.
forbidden_role HTTP 403O papel de quem chama nesta empresa não permite esta ação.
module_not_subscribed HTTP 403A empresa não assina o módulo desta rota.
tenant_mismatch HTTP 403A credencial não pertence à empresa do endereço chamado.
tenant_unavailable HTTP 403A empresa está indisponível no momento.

HTTP 404 · Não encontrado

depot_not_found HTTP 404Não existe CD com esse depot_code nesta empresa.

HTTP 409 · Conflito

depot_inactive HTTP 409O CD está fechado. Reabra o CD antes de mexer no que está dentro dele.
idempotency_key_reused HTTP 409Esta Idempotency-Key já foi usada com outro corpo. Gere uma chave nova para uma escrita nova.
no_active_depot HTTP 409A empresa não tem CD ativo; sem depot_code, não há CD a usar.
order_already_imported HTTP 409Este pedido (order_ref da mesma origem) já foi importado.
stock_not_reservable HTTP 409O disponível do CD (saldo menos o já reservado) não cobre alguma linha do pedido.

HTTP 422 · Não processável

invalid_channel HTTP 422O canal não está no catálogo da Kernos: use o código de um canal (shopee, mercado_livre…) ou omita.
invalid_order_csv HTTP 422O arquivo não está no layout do pedido: cabeçalho order_ref;customer;product;qty;carrier_cnpj, um pedido por arquivo.
invalid_order_json HTTP 422O pedido não está no formato declarado no corpo da rota; o field diz qual campo.
invalid_origin HTTP 422A origem não está no catálogo da Kernos: use o código do parceiro que manda o pedido (bling, tiny…) ou omita.
invalid_qty HTTP 422Quantidade inválida: um inteiro maior que zero.
order_line_unknown_product HTTP 422Há linha com produto fora do catálogo (nem pelo EAN, nem pelo SKU). Cadastre o produto antes de importar.

HTTP 429 · Muitos pedidos

rate_limited HTTP 429Muitos pedidos por segundo com esta chave. Espere o Retry-After, em segundos, e tente de novo.
curlNodePythonPHPJavaC#GoRust
Cria um pedido de venda aberto, com a reserva feita
curl -X POST "https://stag.kernos.com.br/v1/objects/sales-order" \
  -H "Authorization: Bearer ksk_test_…" \
  -H "Kernos-Version: 2026-10-03" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "order_ref": "PED-1001",
    "customer": "Loja Centro",
    "lines": [{ "product": "7891234567895", "qty": 2 }]
  }'
Resposta · 200 (a forma, sem dado real)
{
  "ok": true,
  "data": {
    "sales_order": {
      "carrier_cnpj": "…",
      "channel": "…",
      "channel_ref": "…",
      "customer": "…",
      "customer_area": "…",
      "id": "3f1e0c8a-5b7d-4c21-9a3e-0b1c2d3e4f50",
      "lines": 0,
      "minted": 0,
      "order_ref": "…",
      "origin": "…",
      "outcome": "ok",
      "paid_note": "…",
      "short_units": 0,
      "shortage": [
        {
          "product_id": "3f1e0c8a-5b7d-4c21-9a3e-0b1c2d3e4f50",
          "qty": 0,
          "seq": 0,
          "short_qty": 0
        }
      ],
      "status": "open",
      "units": 0
    }
  },
  "error": null,
  "error_code": null,
  "field": null,
  "trace_id": null
}
Ambiente

ksk_test_ fala com https://stag.kernos.com.br; ksk_live_, com https://api.kernos.com.br. O prefixo da chave escolhe o endereço.