Recebimentos › Importar

Abre um recebimento a partir da NF-e do fornecedor

POST/v1/objects/receipt

O XML da nota vira o recebimento e a OS de conferência na doca. A mesma chave de nota duas vezes recusa com nfe_already_received. Item sem cadastro, quantidade fracionada ou lote faltando no item que controla lote recusam a nota inteira.

Ação da chave: receipt.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

depot_code string

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

dock_location_code string

A posição de doca onde a carga chega. Sem ela, a doca do CD.

xml string OBRIGATÓRIO

O XML da NF-e do fornecedor (o nfeProc ou a NFe).

Devolve

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

receipt objeto OBRIGATÓRIO

14 campos

costs_updated integer

Itens cujo custo a nota atualizou.

id uuid

kind string

purchase para a nota do fornecedor, return para a devolução do cliente.

lines integer

minted integer

Códigos curtos criados (recebimento e OS).

nfe_key string, ou nulo

sales_order_id uuid, ou nulo

status string

stops integer

As paradas da OS de conferência.

stops_at_dock integer

supplier_name string, ou nulo

work_order_id uuid

work_order_kind "receive"

work_order_status string

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.

dock_not_found HTTP 404A doca informada não existe neste CD.

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.

nfe_already_received HTTP 409Esta NF-e já foi recebida. Use o recebimento que existe em vez de importar de novo.

no_active_depot HTTP 409A empresa não tem CD ativo; sem depot_code, não há CD a usar.

HTTP 422 · Não processável

fractional_qty HTTP 422Há item com quantidade fracionada, e o saldo conta unidades inteiras. Cadastre o item na unidade menor.

invalid_nfe_xml HTTP 422O arquivo não é o XML de uma NF-e autorizada que dê para ler (o DANFE em PDF não serve).

lot_required HTTP 422O produto é rastreado por lote: diga de qual lote é o item.

unknown_product HTTP 422Há item na nota fora do catálogo. Cadastre o item e importe a nota de novo; a nota inteira volta.

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