KernosDevelopers
Sair
Referência Ordens de serviço › Criar
Ordens de serviço › Criar

Abre uma OS de guarda, separação, contagem, movimento ou retirada

POST/v1/objects/work-order

kind é putaway, pick, count, move ou unplace. Cada item diz o produto (ean_or_sku ou product_id), a posição e a quantidade; o move pede também from_location_code. A contagem de um corredor inteiro é scope: aisle com location_code, sem itens. O recebimento não se abre por aqui: nasce da nota.

Ação da chave: work_order.create

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

depot_code string

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

items lista de objeto
8 campos
ean_or_sku string

O EAN ou o SKU do item (ou product_id).

from_location_code string

No move: a posição de onde sai.

location_code string

A posição, com ou sem separador.

lot_code string

Obrigatório no item que controla lote.

place_kind "picking" | "bulk" | ""

Na guarda: a face de separação ou o pulmão; bulk por padrão.

product_id uuid
qty integer ou string

Inteiro maior que zero.

stock_status string

No move: o estado do saldo que se move; available por padrão.

kind "putaway" | "pick" | "count" | "move" | "unplace" OBRIGATÓRIO
location_code string

Com scope: aisle: o corredor.

priority integer ou string

1, 2 ou 3.

scope "position" | "aisle" | ""

aisle só na contagem: as paradas são o corredor inteiro de location_code.

source "qr-camera" | "code128-gun" | "typed" | "import" OBRIGATÓRIO

De onde veio o pedido de escrita: câmera, leitor, digitado ou sistema (import).

Devolve

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

work_order objeto OBRIGATÓRIO
8 campos
depot_code string
id uuid
items integer
items_done integer
kind string

receive, putaway, pick, count, move, replenish ou unplace.

priority integer
short_code string, ou nulo
status string

open, in_progress, done ou cancelled.

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.
not_found HTTP 404Não existe objeto com esse identificador 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.
other_depot HTTP 409A posição é de outro CD.
picking_face_exists HTTP 409O produto já tem posição de separação neste CD. Guarde como pulmão ou desenderece a separação antes.

HTTP 422 · Não processável

invalid_kind HTTP 422Tipo de ordem de serviço inválido: use um dos valores declarados no campo.
invalid_move_origin HTTP 422Transferência precisa da posição de origem, além da de destino.
invalid_params HTTP 422Um parâmetro está fora do formato declarado; o field diz qual.
invalid_place_kind HTTP 422Tipo de guarda inválido para esta parada.
invalid_priority HTTP 422Prioridade inválida: use um dos valores declarados no campo.
invalid_qty HTTP 422Quantidade inválida: um inteiro maior que zero.
invalid_scope HTTP 422Recontar o corredor inteiro só existe na ordem de contagem.
invalid_source HTTP 422Origem da leitura inválida: use um dos valores declarados no campo.
items_required HTTP 422A ordem precisa de pelo menos uma parada.
lot_not_found HTTP 422O lote não existe para este produto. O lote nasce no recebimento da nota.
lot_required HTTP 422O produto é rastreado por lote: diga de qual lote é o item.
no_aisle HTTP 422O padrão de endereço deste CD não tem corredor: reconte posição por posição.

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
Abre uma OS de guarda, separação, contagem, movimento ou retirada
curl -X POST "https://stag.kernos.com.br/v1/objects/work-order" \
  -H "Authorization: Bearer ksk_test_…" \
  -H "Kernos-Version: 2026-10-03" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "count",
    "source": "import",
    "items": [
      {
        "ean_or_sku": "7899990000021",
        "location_code": "TREINO-01",
        "qty": 5
      }
    ]
  }'
Resposta · 200 (a forma, sem dado real)
{
  "ok": true,
  "data": {
    "work_order": {
      "depot_code": "…",
      "id": "3f1e0c8a-5b7d-4c21-9a3e-0b1c2d3e4f50",
      "items": 0,
      "items_done": 0,
      "kind": "…",
      "priority": 0,
      "short_code": "…",
      "status": "…"
    }
  },
  "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.