# 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)
- `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`](/erros/invalid_idempotency_key.md) (HTTP 400): Toda escrita pede o cabeçalho `Idempotency-Key` com um UUID.
- [`version_unknown`](/erros/version_unknown.md) (HTTP 400): A `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`](/erros/api_key_expired.md) (HTTP 401): A chave venceu. Gire a chave no painel e use a nova.
- [`api_key_wrong_environment`](/erros/api_key_wrong_environment.md) (HTTP 401): A chave é do outro ambiente: `ksk_test_` vai em https://stag.kernos.com.br, `ksk_live_` em https://api.kernos.com.br.
- [`unauthenticated`](/erros/unauthenticated.md) (HTTP 401): Credencial ausente, inválida ou expirada.
### HTTP 403 · Sem permissão
- [`agent_token_out_of_scope`](/erros/agent_token_out_of_scope.md) (HTTP 403): O 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`](/erros/api_key_action_not_granted.md) (HTTP 403): A chave não tem esta ação. Edite as ações da chave no painel.
- [`api_key_out_of_scope`](/erros/api_key_out_of_scope.md) (HTTP 403): A chave só vale nas rotas do contrato público.
- [`depot_out_of_reach`](/erros/depot_out_of_reach.md) (HTTP 403): Quem chama não alcança o CD deste objeto. Peça alcance ao CD ou use outra credencial.
- [`forbidden_role`](/erros/forbidden_role.md) (HTTP 403): O papel de quem chama nesta empresa não permite esta ação.
- [`module_not_subscribed`](/erros/module_not_subscribed.md) (HTTP 403): A empresa não assina o módulo desta rota.
- [`tenant_mismatch`](/erros/tenant_mismatch.md) (HTTP 403): A credencial não pertence à empresa do endereço chamado.
- [`tenant_unavailable`](/erros/tenant_unavailable.md) (HTTP 403): A empresa está indisponível no momento.
### HTTP 404 · Não encontrado
- [`depot_not_found`](/erros/depot_not_found.md) (HTTP 404): Não existe CD com esse `depot_code` nesta empresa.
- [`dock_not_found`](/erros/dock_not_found.md) (HTTP 404): A doca informada não existe neste CD.
### HTTP 409 · Conflito
- [`depot_inactive`](/erros/depot_inactive.md) (HTTP 409): O CD está fechado. Reabra o CD antes de mexer no que está dentro dele.
- [`idempotency_key_reused`](/erros/idempotency_key_reused.md) (HTTP 409): Esta `Idempotency-Key` já foi usada com outro corpo. Gere uma chave nova para uma escrita nova.
- [`nfe_already_received`](/erros/nfe_already_received.md) (HTTP 409): Esta NF-e já foi recebida. Use o recebimento que existe em vez de importar de novo.
- [`no_active_depot`](/erros/no_active_depot.md) (HTTP 409): A empresa não tem CD ativo; sem `depot_code`, não há CD a usar.
### HTTP 422 · Não processável
- [`fractional_qty`](/erros/fractional_qty.md) (HTTP 422): Há item com quantidade fracionada, e o saldo conta unidades inteiras. Cadastre o item na unidade menor.
- [`invalid_nfe_xml`](/erros/invalid_nfe_xml.md) (HTTP 422): O arquivo não é o XML de uma NF-e autorizada que dê para ler (o DANFE em PDF não serve).
- [`lot_required`](/erros/lot_required.md) (HTTP 422): O produto é rastreado por lote: diga de qual lote é o item.
- [`unknown_product`](/erros/unknown_product.md) (HTTP 422): Há 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`](/erros/rate_limited.md) (HTTP 429): Muitos pedidos por segundo com esta chave. Espere o `Retry-After`, em segundos, e tente de novo.
#### curl
**Abre um recebimento a partir da NF-e do fornecedor**
```sh
curl -X POST "https://stag.kernos.com.br/v1/objects/receipt" \
-H "Authorization: Bearer ksk_test_…" \
-H "Kernos-Version: 2026-10-03" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"xml": "2026-10-03T10:15:00-03:0012345678000195Fornecedor ExemploCAM-AZ-G7899990000021Camiseta azul G10.0000UN",
"dock_location_code": "TREINO-DOCA"
}'
```
#### Node
**Abre um recebimento a partir da NF-e do fornecedor**
```js
import { Kernos } from '@kernosbr/kernos'
const kernos = new Kernos(process.env.KERNOS_API_KEY)
const result = await kernos.receipt.import({
xml: '2026-10-03T10:15:00-03:0012345678000195Fornecedor ExemploCAM-AZ-G7899990000021Camiseta azul G10.0000UN',
dock_location_code: 'TREINO-DOCA'
})
```
#### Python
**Abre um recebimento a partir da NF-e do fornecedor**
```python
import os
from kernos import Kernos
kernos = Kernos(os.environ["KERNOS_API_KEY"])
result = kernos.receipt.import_({
"xml": "2026-10-03T10:15:00-03:0012345678000195Fornecedor ExemploCAM-AZ-G7899990000021Camiseta azul G10.0000UN",
"dock_location_code": "TREINO-DOCA"
})
```
#### PHP
**Abre um recebimento a partir da NF-e do fornecedor**
```php
receipt->import([
'xml' => '2026-10-03T10:15:00-03:0012345678000195Fornecedor ExemploCAM-AZ-G7899990000021Camiseta azul G10.0000UN',
'dock_location_code' => 'TREINO-DOCA'
]);
```
#### Java
**Abre um recebimento a partir da NF-e do fornecedor**
```java
Kernos kernos = new Kernos(System.getenv("KERNOS_API_KEY"));
JsonNode result = kernos.receipt().importNfe(Map.of(
"xml", "2026-10-03T10:15:00-03:0012345678000195Fornecedor ExemploCAM-AZ-G7899990000021Camiseta azul G10.0000UN",
"dock_location_code", "TREINO-DOCA"
));
```
#### C#
**Abre um recebimento a partir da NF-e do fornecedor**
```csharp
var kernos = new KernosClient(Environment.GetEnvironmentVariable("KERNOS_API_KEY"));
var result = await kernos.Receipt.ImportAsync(new {
xml = "2026-10-03T10:15:00-03:0012345678000195Fornecedor ExemploCAM-AZ-G7899990000021Camiseta azul G10.0000UN",
dock_location_code = "TREINO-DOCA"
});
```
#### Go
**Abre um recebimento a partir da NF-e do fornecedor**
```go
client, err := kernos.New(os.Getenv("KERNOS_API_KEY"))
result, err := client.Receipt.Import(ctx, map[string]any{
"xml": "2026-10-03T10:15:00-03:0012345678000195Fornecedor ExemploCAM-AZ-G7899990000021Camiseta azul G10.0000UN",
"dock_location_code": "TREINO-DOCA",
})
```
#### Rust
**Abre um recebimento a partir da NF-e do fornecedor**
```rust
let kernos = Kernos::new(&std::env::var("KERNOS_API_KEY")?)?;
let result = kernos.receipt().import(&json!({
"xml": "2026-10-03T10:15:00-03:0012345678000195Fornecedor ExemploCAM-AZ-G7899990000021Camiseta azul G10.0000UN",
"dock_location_code": "TREINO-DOCA"
}), None)?;
```
**Resposta · 200 (a forma, sem dado real)**
```json
{
"ok": true,
"data": {
"receipt": {
"costs_updated": 0,
"id": "3f1e0c8a-5b7d-4c21-9a3e-0b1c2d3e4f50",
"kind": "…",
"lines": 0,
"minted": 0,
"nfe_key": "…",
"sales_order_id": "3f1e0c8a-5b7d-4c21-9a3e-0b1c2d3e4f50",
"status": "…",
"stops": 0,
"stops_at_dock": 0,
"supplier_name": "…",
"work_order_id": "3f1e0c8a-5b7d-4c21-9a3e-0b1c2d3e4f50",
"work_order_kind": "receive",
"work_order_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.