Pedidos de venda › Cancelar
Cancela um pedido, e o que já saiu da prateleira volta à posição
POST/v1/objects/sales-order/{id}/cancel
Aberto, o pedido só deixa de reservar. Já separado, a reserva é solta e nasce a OS de devolver à posição (return). Embarcado ou cancelado antes, recusa.
Ação da chave:
sales_order.cancelQuem 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-KeyUm UUID por escrita. Repetida com o mesmo corpo, devolve a mesma resposta sem escrever de novo. Os SDKs mandam sozinhos.
Parâmetros do caminho
id string OBRIGATÓRIO
Corpo
reason string
O motivo, gravado no fato.
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 }:
sales_order objeto OBRIGATÓRIO
12 campos
closed_orders lista de any
Só no pedido já separado: as OS que fecharam por ficar sem parada.
customer string, ou nulo
depot_id uuid
dropped_stops integer
Só no pedido já separado: as paradas de separação que saíram.
freed_units integer
Só no pedido já separado: as unidades cuja reserva foi solta.
id uuid
lines integer
order_ref string
return objeto
Só no pedido já separado: a OS de devolver à posição.
status "canceled"
touched_orders lista de uuid
Só no pedido já separado: as OS mexidas.
units integer
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
not_found HTTP 404Não existe objeto com esse identificador nesta empresa.HTTP 409 · Conflito
idempotency_key_reused HTTP 409Esta Idempotency-Key já foi usada com outro corpo. Gere uma chave nova para uma escrita nova.order_loaded HTTP 409O pedido tem volume carregado num envio: tire o volume do envio antes de cancelar.order_not_open HTTP 409Um dos pedidos já está em outra onda ou já saiu.HTTP 422 · Não processável
invalid_source HTTP 422Origem da leitura inválida: use um dos valores declarados no campo.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
Cancela um pedido, e o que já saiu da prateleira volta à posição
curl -X POST "https://stag.kernos.com.br/v1/objects/sales-order/<id>/cancel" \
-H "Authorization: Bearer ksk_test_…" \
-H "Kernos-Version: 2026-10-03" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "source": "import", "reason": "Cliente desistiu" }'Cancela um pedido, e o que já saiu da prateleira volta à posição
import { Kernos } from '@kernosbr/kernos'
const kernos = new Kernos(process.env.KERNOS_API_KEY)
const result = await kernos.salesOrder.cancel('<id>', { source: 'import', reason: 'Cliente desistiu' })Cancela um pedido, e o que já saiu da prateleira volta à posição
import os
from kernos import Kernos
kernos = Kernos(os.environ["KERNOS_API_KEY"])
result = kernos.sales_order.cancel("<id>", {"source": "import", "reason": "Cliente desistiu"})Cancela um pedido, e o que já saiu da prateleira volta à posição
<?php
$kernos = new Kernos\Kernos(getenv('KERNOS_API_KEY'));
$result = $kernos->salesOrder->cancel('<id>', ['source' => 'import', 'reason' => 'Cliente desistiu']);Cancela um pedido, e o que já saiu da prateleira volta à posição
Kernos kernos = new Kernos(System.getenv("KERNOS_API_KEY"));
JsonNode result = kernos.salesOrder().cancel("<id>", Map.of("source", "import", "reason", "Cliente desistiu"));Cancela um pedido, e o que já saiu da prateleira volta à posição
var kernos = new KernosClient(Environment.GetEnvironmentVariable("KERNOS_API_KEY"));
var result = await kernos.SalesOrder.CancelAsync("<id>", new { source = "import", reason = "Cliente desistiu" });Cancela um pedido, e o que já saiu da prateleira volta à posição
client, err := kernos.New(os.Getenv("KERNOS_API_KEY"))
result, err := client.SalesOrder.Cancel(ctx, "<id>", map[string]any{"source": "import", "reason": "Cliente desistiu"})Cancela um pedido, e o que já saiu da prateleira volta à posição
let kernos = Kernos::new(&std::env::var("KERNOS_API_KEY")?)?;
let result = kernos.sales_order().cancel("<id>", &json!({ "source": "import", "reason": "Cliente desistiu" }), None)?;Resposta · 200 (a forma, sem dado real)
{
"ok": true,
"data": {
"sales_order": {
"closed_orders": [
null
],
"customer": "…",
"depot_id": "3f1e0c8a-5b7d-4c21-9a3e-0b1c2d3e4f50",
"dropped_stops": 0,
"freed_units": 0,
"id": "3f1e0c8a-5b7d-4c21-9a3e-0b1c2d3e4f50",
"lines": 0,
"order_ref": "…",
"return": {},
"status": "canceled",
"touched_orders": [
"3f1e0c8a-5b7d-4c21-9a3e-0b1c2d3e4f50"
],
"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.