# Dokument
> Schemat ocost.document.v1 w pojęciach EN 16931 (odwzorowywalny na UBL i CII): przykład, rodzaj i kierunek, źródła, kontrole, wersje oraz każde pole i każda wartość.
>
> Najpierw: [Wysłać plik i go odczytać](https://ocost.io/docs/pl/files.md)

Ocost zwraca każdy odczytany dokument jako `ocost.document.v1`. Pobierz go przez `GET /public/v1/files/{file_id}/document` lub `GET /public/v1/documents/{document_id}`. Pola są zgodne z EN 16931, normą stojącą za XRechnung, ZUGFeRD i Peppol UBL. Każde pole wskazuje swój termin biznesowy (BT-…) lub grupę (BG-…), więc daje się odwzorować na UBL lub CII.

Waliduj względem [JSON Schema](https://ocost.io/docs/schemas/ocost.document.v1.json) albo generuj z niego typy. [Pola](#pola) i [Wartości](#wartosci) poniżej wymieniają wszystko, co zawiera.

## Przykład

Faktura przychodząca z dwiema pozycjami po 19 % i 2 % Skonto w ciągu 14 dni:

```json
{
  "schema": "ocost.document.v1",
  "id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11",
  "file_id": "01a1b08c-6e3a-7562-8f4a-7924722667b1",
  "pages": [1],
  "kind": "invoice",
  "kind_detail": "invoice",
  "direction": "incoming",
  "type_code": "380",
  "number": "RE-2026-1187",
  "issue_date": "2026-11-03",
  "due_date": "2026-12-03",
  "delivery_date": "2026-10-30",
  "invoicing_period_start": null,
  "invoicing_period_end": null,
  "valid_until": null,
  "currency": "EUR",
  "buyer_reference": null,
  "order_reference": "PO-2316",
  "order_references": ["PO-2316"],
  "preceding_invoice": null,
  "seller": {
    "name": "Musterbüro Lieferant GmbH",
    "vat_id": "DE123456789",
    "tax_registration_id": null,
    "legal_registration_id": "HRB 12345",
    "address": { "street": "Beispielweg 4", "postal_code": "50667", "city": "Köln", "country": "DE" },
    "contact": { "email": "rechnung@lieferant.example", "phone": null },
    "website": null
  },
  "buyer": {
    "name": "Beispiel Handel GmbH",
    "vat_id": "DE987654321",
    "tax_registration_id": null,
    "legal_registration_id": null,
    "address": { "street": "Hauptstraße 1", "postal_code": "40213", "city": "Düsseldorf", "country": "DE" },
    "contact": null,
    "website": null
  },
  "payee": null,
  "deliver_to": null,
  "other_parties": [],
  "payment": {
    "means_code": "58",
    "means": "transfer",
    "iban": "DE02120300000000202051",
    "bic": null,
    "iban_holder": null,
    "assigned_to": null,
    "terms": "14 Tage 2 % Skonto, 30 Tage netto",
    "net_days": 30,
    "paid_on": null
  },
  "early_payment_discounts": [
    { "days": 14, "percent": 2, "base_amount": null, "due_date": "2026-11-17" }
  ],
  "totals": { "net": 1068, "tax": 202.92, "gross": 1270.92, "payable": null, "prices_include_vat": false },
  "vat_breakdown": [
    { "category": "S", "rate": 19, "taxable_amount": 1068, "tax_amount": 202.92, "exemption_reason": null }
  ],
  "lines": [
    {
      "id": "1", "name": "Bürostuhl ErgoPlus schwarz", "seller_item_id": "ES-200", "standard_item_id": null,
      "quantity": 4, "unit": "H87", "price": 189, "base_quantity": null, "net_amount": 756,
      "discount_percent": null, "vat_category": "S", "vat_rate": 19,
      "ordered_quantity": null, "backordered_quantity": null, "batch": null, "pzn": null,
      "attributes": { "colour": "schwarz" }
    },
    {
      "id": "2", "name": "Montage", "seller_item_id": null, "standard_item_id": null,
      "quantity": 4, "unit": "HUR", "price": 78, "base_quantity": null, "net_amount": 312,
      "discount_percent": null, "vat_category": "S", "vat_rate": 19,
      "ordered_quantity": null, "backordered_quantity": null, "batch": null, "pzn": null,
      "attributes": {}
    }
  ],
  "deductions": [],
  "card": null,
  "worked_out": [],
  "sources": {
    "number": { "page": 1, "quote": "RE-2026-1187", "box": null, "confidence": "read", "why": null },
    "totals.gross": { "page": 1, "quote": "1.270,92 €", "box": { "x0": 0.7012, "y0": 0.6831, "x1": 0.8874, "y1": 0.6995 }, "confidence": "checked", "why": null },
    "seller.vat_id": { "page": 1, "quote": "DE123456789", "box": null, "confidence": "checked", "why": null }
  },
  "checks": [
    { "name": "vat", "passed": true, "sums": true, "fields": ["totals.net", "totals.tax"], "at": "19" },
    { "name": "gross", "passed": true, "sums": true, "fields": ["totals.net", "totals.tax", "totals.gross"], "at": null }
  ],
  "tax_check": { "case": "standard", "missing": [] },
  "attention": [],
  "possible_duplicate_of": null,
  "read_with": "reader"
}
```

## Rodzaj i kierunek

Rozgałęziaj logikę według `kind`. Grupuje on typy dokumentów Ocost w kilka, na przykład `invoice` lub `delivery_note`. `kind_detail` podaje dokładny typ. `type_code` podaje kod UNCL 1001 faktury, na przykład `380`.

`direction` mówi, czy dokument jest `incoming` od dostawcy, `outgoing` od Twojej firmy, czy `unsure`. Ocost ustala to na podstawie Twoich danych w [Ustawienia › Firma](https://app.ocost.io/settings/company), więc dbaj o ich poprawność.

## Identyfikatory z każdego kraju

`identifiers` każdej strony wymienia wydrukowane dla niej numery według `scheme`, na przykład `UA_EDRPOU`, `UA_RNOKPP`, `UA_IPN` lub `PL_NIP`. Żaden szablon nie jest potrzebny. `valid` ma wartość `false`, gdy cyfra kontrolna się nie zgadza, i `null`, gdy schemat jej nie ma.

Dokumenty, identyfikatory i zasady VAT każdego kraju mają własną stronę: [Niemcy](https://ocost.io/docs/pl/germany.md), [Ukraina](https://ocost.io/docs/pl/ukraine.md), [Wielka Brytania](https://ocost.io/docs/pl/uk.md), [Stany Zjednoczone](https://ocost.io/docs/pl/us.md) i [Mołdawia](https://ocost.io/docs/pl/moldova.md).

## Płatność na rzecz faktora

Na fakturze, której wierzytelność przelano na faktora (Zession, faktoring), `payment.iban` to rachunek faktora. `payment.assigned_to` podaje faktora, a `payment.iban_holder` posiadacza rachunku. `payee` zawiera faktora, gdy Ocost odczytał go jako stronę.

```json
{
  "payment": {
    "iban": "DE89370400440532013000",
    "iban_holder": "Muster Factoring GmbH",
    "assigned_to": { "name": "Muster Factoring GmbH" }
  }
}
```

## Jak zapisywane są wartości

| Wartość | Zapis |
| --- | --- |
| Kwoty i ilości | Dokładne liczby JSON w najkrótszej postaci, na przykład `1270.92` lub `595`. Najwyżej 15 cyfr znaczących. Przed obliczeniami wczytaj je jako liczby dziesiętne. |
| Stawki | Procenty, na przykład `19` lub `5.5`. |
| Daty i kody | ISO 8601 (`2026-11-03`), ISO 4217 (`EUR`), ISO 3166-1 alpha-2 (`DE`), jednostki UNECE (`HUR`). [Jednostki i kody](https://ocost.io/docs/pl/units.md) je wymieniają. |
| Kody odczytane błędnie | `null`, nigdy wydrukowany tekst. To samo dotyczy IBAN i BIC. |
| Brakujące wartości | `null`, gdy nie wydrukowano wartości lub Ocost nie był pewny. Ocost nigdy nie zgaduje. Przez MCP takie pole jest za to pomijane. |

## Jak pewny jest Ocost

`sources` podaje dla każdej wartości, według jej ścieżki, gdzie ją odczytano: jej `page` i jej `quote`. Jej `confidence` przyjmuje jedną z trzech wartości:

| Pewność | Znaczenie |
| --- | --- |
| `checked` | Potwierdziła ją kontrola albo pochodzi z e-faktury. |
| `read` | Nic nie przemawia przeciwko niej. |
| `doubt` | Kontrola się nie powiodła, a `why` ją wskazuje. Albo jej słów nie znaleziono na jej stronie. |

`box` zaznacza wartość na jej stronie: `x0`, `y0` (lewy górny róg) i `x1`, `y1` (prawy dolny róg), jako ułamki strony od jej lewego górnego rogu, od 0 do 1. Strona to `page` tak, jak pokazuje ją `GET /public/v1/files/{id}/content`, po uwzględnieniu obrotu. Na tekście pliku PDF ramka jest dokładna, na skanie szacuje ją OCR. Bez zapisanej ramki ma wartość `null`, a jedyną informacją jest `quote`.

`checks` wymienia każdą kontrolę, którą Ocost wykonał w kodzie, z `passed`. Kontrole oznaczone `sums: true` sumują kwoty. Wypełniaj fakturę bez spojrzenia człowieka tylko wtedy, gdy każda z nich przeszła.

`attention` wymienia to, na co człowiek powinien spojrzeć przed zaksięgowaniem, na przykład możliwy duplikat. `tax_check` zawiera kontrolę faktury przychodzącej według prawa niemieckiego, jak objaśnia strona [Niemcy](https://ocost.io/docs/pl/germany.md#sprawdzenie-faktury).

```python
from decimal import Decimal

document = session.get(f"{API}/files/{file_id}/document", timeout=15).json()
sums_hold = all(c["passed"] for c in document["checks"] if c["sums"])
gross = document["totals"]["gross"]  # an exact JSON number, or None
gross = None if gross is None else Decimal(str(gross))
doubts = [path for path, s in document["sources"].items() if s["confidence"] == "doubt"]
```

```javascript
const document = await fetch(`${API}/documents/${documentId}`, { headers: auth }).then((r) => r.json());
const sumsHold = document.checks.filter((c) => c.sums).every((c) => c.passed);
// Kwoty są dokładnymi liczbami. Licz biblioteką liczb dziesiętnych, z String(kwota).
console.log(document.number, document.totals.gross, sumsHold);
```

## Wersje

W ramach v1 Ocost może dodać wartość do listy, ale nigdy nie zmienia nazwy pola ani wartości i nigdy ich nie usuwa. Nieznany `kind` traktuj jako `other` i nigdy nie przerywaj działania z powodu nieznanej wartości. Zmiana niezgodna wstecz przyjdzie jako `ocost.document.v2` pod `/public/v2`, a v1 zostanie jeszcze przez 12 miesięcy.

## Zmiany

[Dziennik zmian](https://ocost.io/docs/pl/changelog.md) wymienia każdą zmianę, od najnowszej.

## Pola

Każde pole, wypisane z kodu Ocost. [JSON Schema](https://ocost.io/docs/schemas/ocost.document.v1.json) zawiera to samo. Opisy są tam, tak jak tutaj, po angielsku.

### `Document`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `schema` | `ocost.document.v1` | Always this |
| `id` | uuid | The document |
| `file_id` | uuid | The file it is in |
| `pages` | lista integer | Its pages in the file, from 1 |
| `kind` | wyliczenie, [Wartości](#wartosci) | What a document is, grouped so an integrator branches on few; the exact kind is `kind_detail`. |
| `kind_detail` | wyliczenie, [Wartości](#wartosci) | The exact kind, one of Ocost's document types, for information |
| `direction` | wyliczenie, [Wartości](#wartosci) | Whether the business received or issued it. |
| `type_code` | string (`380`) lub null | BT-3, UNCL 1001 |
| `number` | string lub null | BT-1 |
| `issue_date` | date lub null | BT-2 |
| `due_date` | date lub null | BT-9 |
| `delivery_date` | date lub null | BT-72 |
| `invoicing_period_start` | date lub null | BT-73 |
| `invoicing_period_end` | date lub null | BT-74 |
| `valid_until` | date lub null | A quote's |
| `currency` | string (`EUR`) lub null | BT-5, ISO 4217 |
| `buyer_reference` | string lub null | BT-10 |
| `order_reference` | string lub null | BT-13 |
| `order_references` | lista string | Every order it names |
| `preceding_invoice` | string lub null | BT-25; a tax invoice's: the invoice or act it is for |
| `contract_reference` | string lub null | BT-12: the contract it refers to (an act's) |
| `tax_registration` | `TaxRegistration` lub null | A tax invoice's registration, where printed |
| `seller` | `Party` lub null | BG-4 |
| `buyer` | `Party` lub null | BG-7 |
| `payee` | `Party` lub null | BG-10: when not the seller |
| `deliver_to` | `Address` lub null | BG-15 |
| `other_parties` | lista `OtherParty` | Every other party named |
| `payment` | `Payment` | BG-16. |
| `early_payment_discounts` | lista `EarlyPaymentDiscount` | Skonto: XRechnung's #SKONTO# in BT-20. |
| `totals` | `Totals` | BG-22. |
| `vat_breakdown` | lista `VatGroup` | BG-23. |
| `lines` | lista `Line` | BG-25. |
| `deductions` | lista `Deduction` | A final invoice's: an earlier invoice it takes off. |
| `card` | `Card` lub null | What a document without fields of its own says: a title, a summary and its facts (deadlines first). |
| `worked_out` | lista `WorkedOut` | An amount Ocost worked out because the one read can't be it. |
| `sources` | mapa `Source` | Per value, by its path |
| `checks` | lista `Check` | A check Ocost ran in code, and whether it passed. |
| `tax_check` | `TaxCheck` lub null | An incoming invoice's § 14 UStG check (Germany's rules). |
| `attention` | lista wyliczenie, [Wartości](#wartosci) | What a person should look at before booking it. |
| `possible_duplicate_of` | uuid lub null | An earlier document of the same kind, number and seller |
| `read_with` | wyliczenie, [Wartości](#wartosci) | How Ocost read it |

### `TaxRegistration`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `number` | string lub null | Its registration number |
| `date` | date lub null | The day it was registered |

### `Party`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `name` | string lub null | BT-27 (seller), BT-44 (buyer) |
| `identifiers` | lista `PartyIdentifier` | Every identifier printed for it, by scheme (BT-29, BT-46 in any country): an ЄДРПОУ, a РНОКПП, an ІПН, a NIP, … |
| `vat_id` | string lub null | BT-31, BT-48 |
| `tax_registration_id` | string lub null | BT-32: the tax number (Steuernummer) |
| `legal_registration_id` | string lub null | BT-30, BT-47: the register entry (HRB …) |
| `address` | `Address` lub null | BG-5, BG-8 |
| `contact` | `Contact` lub null | BG-6, BG-9 |
| `website` | string lub null | As printed: a host, with or without its scheme |

### `Address`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `street` | string lub null | BT-35 (seller), BT-50 (buyer) |
| `postal_code` | string lub null | BT-38, BT-53 |
| `city` | string lub null | BT-37, BT-52 |
| `country` | string (`DE`) lub null | BT-40, BT-55: ISO 3166-1 alpha-2 |

### `OtherParty`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `name` | string lub null | BT-27 (seller), BT-44 (buyer) |
| `identifiers` | lista `PartyIdentifier` | Every identifier printed for it, by scheme (BT-29, BT-46 in any country): an ЄДРПОУ, a РНОКПП, an ІПН, a NIP, … |
| `vat_id` | string lub null | BT-31, BT-48 |
| `tax_registration_id` | string lub null | BT-32: the tax number (Steuernummer) |
| `legal_registration_id` | string lub null | BT-30, BT-47: the register entry (HRB …) |
| `address` | `Address` lub null | BG-5, BG-8 |
| `contact` | `Contact` lub null | BG-6, BG-9 |
| `website` | string lub null | As printed: a host, with or without its scheme |
| `role` | wyliczenie, [Wartości](#wartosci) | What it is to the document |
| `printed_role` | string lub null | The words printed for its role |

### `Payment`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `means_code` | wyliczenie, [Wartości](#wartosci) lub null | BT-81, UNCL 4461; null when it doesn't say or it was paid already |
| `means` | wyliczenie, [Wartości](#wartosci) lub null | The same, as a word |
| `iban` | string (`DE02120300000000202051`) lub null | BT-84, without spaces |
| `bic` | string (`BYLADEM1001`) lub null | BT-86 |
| `iban_holder` | string lub null | BT-85: the holder of `iban`, as printed |
| `assigned_to` | `Factor` lub null | The factor its assignment note (Abtretung, Zession, factoring) names; `iban` is then the factor's |
| `terms` | string lub null | BT-20, as printed |
| `net_days` | integer lub null | The days the terms give to pay in full from the issue date |
| `paid_on` | date lub null | The day it says it was paid or charged, where printed |

### `EarlyPaymentDiscount`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `days` | integer |  |
| `percent` | liczba dziesiętna | 2 for 2 % |
| `base_amount` | liczba dziesiętna lub null | What it is taken off, where printed; null: the amount due |
| `due_date` | date lub null | The last day for it: the issue date plus `days` |

### `Totals`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `net` | liczba dziesiętna lub null | BT-109 |
| `tax` | liczba dziesiętna lub null | BT-110 |
| `gross` | liczba dziesiętna lub null | BT-112 |
| `payable` | liczba dziesiętna lub null | BT-115: what is left to pay; null when it is the gross |
| `prices_include_vat` | boolean | Its lines' prices and amounts include VAT (a receipt) |

### `VatGroup`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `category` | wyliczenie, [Wartości](#wartosci) lub null | BT-118 |
| `rate` | liczba dziesiętna lub null | BT-119, percent: 19 |
| `taxable_amount` | liczba dziesiętna | BT-116 |
| `tax_amount` | liczba dziesiętna | BT-117 |
| `exemption_reason` | string lub null | BT-120 |

### `Line`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `id` | string | BT-126: its position |
| `name` | string | BT-153 |
| `seller_item_id` | string lub null | BT-155: the article number |
| `standard_item_id` | string lub null | BT-157: the GTIN (scheme 0160) |
| `quantity` | liczba dziesiętna lub null | BT-129 |
| `unit` | string (`C62`) lub null | BT-130: UNECE Rec 20 (C62, HUR, KGM) or Rec 21 (XCT); null when none is printed or it is no code |
| `price` | liczba dziesiętna lub null | BT-146: the net price |
| `base_quantity` | liczba dziesiętna lub null | BT-149: how many units `price` is for; null: one |
| `net_amount` | liczba dziesiętna lub null | BT-131 |
| `discount_percent` | liczba dziesiętna lub null | The line's discount: 5 |
| `vat_category` | wyliczenie, [Wartości](#wartosci) lub null | BT-151 |
| `vat_rate` | liczba dziesiętna lub null | BT-152, percent |
| `tax_amount` | liczba dziesiętna lub null | The line's VAT, only as printed on it; null when it prints none |
| `gross_amount` | liczba dziesiętna lub null | The line's total with VAT, only as printed on it; null when it prints none |
| `ordered_quantity` | liczba dziesiętna lub null | A delivery note's |
| `backordered_quantity` | liczba dziesiętna lub null | Still to come |
| `batch` | string lub null | Its batch (Charge), as printed |
| `pzn` | string lub null | A medicine's PZN |
| `attributes` | mapa string | What it is, as printed: colour, size, material, brand, … |

### `Deduction`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `number` | string lub null |  |
| `issue_date` | date lub null |  |
| `net` | liczba dziesiętna lub null |  |
| `tax` | liczba dziesiętna lub null |  |
| `gross` | liczba dziesiętna lub null |  |

### `Card`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `title` | string lub null |  |
| `summary` | string lub null |  |
| `facts` | lista `Fact` |  |

### `WorkedOut`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `field` | wyliczenie, [Wartości](#wartosci) | Its path in this document |
| `printed` | liczba dziesiętna lub null | What was read |
| `rule` | wyliczenie, [Wartości](#wartosci) | How Ocost worked an amount out. |

### `Source`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `page` | integer lub null | Where it was read: the file's page, from 1 |
| `quote` | string lub null | The words it was read from |
| `box` | `Box` lub null | Its rectangle on `page`; null when Ocost kept none (then `quote` is all there is) |
| `confidence` | wyliczenie, [Wartości](#wartosci) | How sure Ocost is of a value, from its checks: never a model's grade. |
| `why` | string lub null | For a doubt: the failed check's `name` |

### `Check`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `name` | wyliczenie, [Wartości](#wartosci) | What it checked; `sums` says whether it is one of the sums |
| `passed` | boolean |  |
| `sums` | boolean | One of the sums (total, vat, vat_net, vat_tax, gross, payable, signs, skonto, deduction, deductions, quantity): fill a bill only when all pass |
| `fields` | lista string (`totals.gross`) | The paths it is about, as `sources` names them |
| `at` | string lub null | The rate or the line it is about |

### `TaxCheck`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `case` | wyliczenie, [Wartości](#wartosci) | Which German rules an incoming invoice is held to. |
| `missing` | lista `TaxItem` |  |

### `PartyIdentifier`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `scheme` | wyliczenie, [Wartości](#wartosci) | What an identifier of a party is. |
| `value` | string | Digits only for the schemes of digits, a VAT ID without spaces, any other as printed |
| `valid` | boolean lub null | Its length and check digit hold; false: in doubt, a misread (never matched on); null: its scheme has no check |

### `Contact`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `email` | string lub null | BT-43, BT-58: an address as printed |
| `phone` | string lub null | BT-42, BT-57: as printed |

### `Factor`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `name` | string | As the assignment note prints it |

### `Fact`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `label` | string | What it is, in the document's words |
| `kind` | wyliczenie, [Wartości](#wartosci) | What a fact on a document's card is. |
| `date` | date lub null |  |
| `amount` | liczba dziesiętna lub null |  |
| `currency` | string (`EUR`) lub null | ISO 4217, of `amount` |
| `number` | liczba dziesiętna lub null |  |
| `text` | string lub null |  |
| `page` | integer lub null |  |

### `Box`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `x0` | number | Its left edge, from the page's left |
| `y0` | number | Its top edge, from the page's top |
| `x1` | number | Its right edge, from the page's left |
| `y1` | number | Its bottom edge, from the page's top |

### `TaxItem`

| Pole | Typ | Znaczenie |
| --- | --- | --- |
| `item` | wyliczenie, [Wartości](#wartosci) | What an invoice lacks, or has wrong, for its case. |
| `law` | string | The paragraph that asks for it |
| `at_stake` | boolean | Missing, it costs the input VAT deduction |

## Wartości

Każda lista wartości, wypisana z kodu Ocost. [JSON Schema](https://ocost.io/docs/schemas/ocost.document.v1.json) i [dokumentacja API](https://ocost.io/docs/openapi.json) zawierają to samo, znaczenia po angielsku. Późniejsza wersja Ocost może dodać wartość w ramach v1. Nieznany `kind` traktuj jako `other`, a każdą inną nieznaną wartość pomiń. W v1 żadna wartość nie zmienia nazwy ani nie znika.

### `kind`

What a document is, grouped so an integrator branches on few; the exact kind is `kind_detail`.

| Wartość | Znaczenie |
| --- | --- |
| `invoice` | An invoice to pay: partial, final, advance, collective, recurring, self-billed (`type_code` says which) |
| `credit_note` | A credit note |
| `invoice_correction` | A corrected invoice |
| `receipt` | A receipt: paid already |
| `pro_forma` | A pro forma invoice: not to pay |
| `delivery_note` | A delivery note |
| `order` | An order: a purchase, service, work or project order |
| `order_confirmation` | An order's or a reservation's confirmation |
| `quote` | A quote (offer) |
| `contract` | A contract: agreements, leases, insurance policies, mandates |
| `statement` | A factor's statement |
| `payment_reminder` | A payment reminder |
| `tax_invoice` | A tax invoice registered with the tax authority (a Ukrainian податкова накладна): VAT evidence, not to pay |
| `other` | Anything else: `kind_detail` and `card` say what |

### `kind_detail`

The exact kind, one of Ocost's document types, for information: branch on `kind`, which groups them (the guide's reference lists which).

Każdy `kind_detail` według `kind`, którym jest:

| kind | kind_detail |
| --- | --- |
| `invoice` | `collective_invoice`, `invoice`, `recurring_rental_invoice`, `fee_invoice`, `advance_payment_invoice`, `credit_invoice`, `final_invoice`, `partial_invoice` |
| `credit_note` | `credit_note` |
| `invoice_correction` | `invoice_correction` |
| `receipt` | `receipt`, `payment_voucher` |
| `pro_forma` | `pro_forma_invoice` |
| `delivery_note` | `delivery_note` |
| `order` | `order`, `order_form`, `project_order`, `service_order`, `work_order`, `purchase_order` |
| `order_confirmation` | `order_confirmation`, `reservation_confirmation` |
| `quote` | `offer` |
| `contract` | `agreement`, `contract`, `insurance_policy`, `mandate`, `lease_contract` |
| `statement` | `statement` |
| `payment_reminder` | `payment_reminder` |
| `tax_invoice` | `tax_invoice` |
| `other` | `acceptance_protocol`, `bonus_payment_notification`, `certificate`, `certificate_of_destruction`, `cost_statement`, `court_order`, `reimbursement`, `customer_statistics`, `decision`, `final_report`, `lump_sum_overview`, `test_report`, `laboratory_report`, `logistics_appendix`, `maintenance_log`, `maintenance_report`, `request_for_medical_consultation`, `notification`, `payroll`, `pay_slip`, `prescription`, `work_record`, `recommendation`, `report`, `inquiry`, `requirement`, `separator_sheet`, `service_report`, `service_documentation`, `declaration`, `time_sheet`, `work_report`, `settlement_amount`, `electronic_summary`, `administrative_fee`, `copy_of_invoice`, `bailiff`, `membership_fee`, `enforcement_case`, `information`, `cost_calculation`, `fee_notice`, `invoice_audit`, `annex`, `direct_debit_advice`, `process_history`, `internal_project_information`, `bank_transaction_report`, `request_for_quotation`, `rejection`, `form` |

### `direction`

Whether the business received or issued it.

| Wartość | Znaczenie |
| --- | --- |
| `incoming` | To the business: a supplier's |
| `outgoing` | The business issued it |
| `unsure` | Its parties don't say |

### `seller.identifiers[].scheme`, `buyer.identifiers[].scheme`, `payee.identifiers[].scheme`, `other_parties[].identifiers[].scheme`

What an identifier of a party is.

| Wartość | Znaczenie |
| --- | --- |
| `UA_EDRPOU` | Ukraine: a legal entity's code ЄДРПОУ, 8 digits |
| `UA_RNOKPP` | Ukraine: a person's or sole trader's (ФОП) РНОКПП, 10 digits |
| `UA_IPN` | Ukraine: the VAT payer's number ІПН, 12 digits |
| `EU_VAT` | A VAT ID with its country prefix (also `vat_id`) |
| `DE_STNR` | Germany: a tax number, Steuernummer |
| `COMMERCIAL_REGISTER` | A register entry with its court (HRB 1234) |
| `PL_NIP` | Poland: NIP, 10 digits |
| `PL_REGON` | Poland: REGON, 9 or 14 digits |
| `PL_KRS` | Poland: KRS number, 10 digits |
| `GB_CRN` | UK: Companies House number, 8 digits or 2 letters and 6 |
| `FR_SIREN` | France: SIREN, 9 digits |
| `FR_SIRET` | France: SIRET, 14 digits |
| `CZ_ICO` | Czechia: IČO, 8 digits |
| `RO_CUI` | Romania: CUI, 2 to 10 digits |
| `NO_ORGNR` | Norway: organisasjonsnummer, 9 digits |
| `FI_YTUNNUS` | Finland: Y-tunnus, 8 digits (without its dash) |
| `US_EIN` | United States: EIN, 9 digits |
| `US_STATE_FILE` | United States: a state's entity or file number |
| `MD_IDNO` | Moldova: IDNO, 13 digits |
| `MD_IDNP` | Moldova: a person's IDNP, 13 digits |
| `MD_VAT` | Moldova: cod TVA, 7 digits |
| `OTHER` | Any other number that identifies the party |

### `other_parties[].role`

What another party is to the document; `printed_role` is its words.

| Wartość | Znaczenie |
| --- | --- |
| `seller` | The seller |
| `buyer` | The buyer |
| `invoicee` | Who it is addressed to, when not the buyer (Rechnungsempfänger) |
| `service_recipient` | Who receives the service, when not the buyer (Leistungsempfänger) |
| `payer` | Who pays, when not the buyer |
| `payee` | Who is paid, when not the seller |
| `ship_to` | Where the goods go (Warenempfänger) |
| `carrier` | Who carries the goods |
| `factor` | Who bought the receivable |
| `debtor` | Whose receivable it is (a factor's debtor) |
| `guarantor` | Who guarantees it (Bürge) |
| `landlord` | The landlord |
| `tenant` | The tenant |
| `subtenant` | The subtenant |
| `contractor` | The contractor |
| `subcontractor` | The subcontractor |
| `principal` | Who commissions the work (Auftraggeber, Bauherr) |
| `agent` | Who acts for a party: a property manager, a broker |
| `insurer` | The insurer |
| `policyholder` | The policyholder |
| `other` | Any other role: `printed_role` says which |

### `payment.means_code`

BT-81: how it is paid, UNCL 4461.

| Wartość | Znaczenie |
| --- | --- |
| `58` | SEPA credit transfer |
| `59` | SEPA direct debit |
| `48` | Bank card |

### `payment.means`

How it is paid, as a word.

| Wartość | Znaczenie |
| --- | --- |
| `transfer` | A credit transfer (`means_code` 58) |
| `direct_debit` | A direct debit (59) |
| `card` | A card (48) |
| `already_paid` | It says it is paid already (no code) |

### `vat_breakdown[].category`, `lines[].vat_category`

BT-118, BT-151: the VAT category, UNCL 5305 as EN 16931 uses it.

| Wartość | Znaczenie |
| --- | --- |
| `S` | Standard rate |
| `Z` | Zero rated goods |
| `E` | Exempt from VAT |
| `AE` | Reverse charge: the buyer owes the VAT |
| `K` | Intra-community supply, VAT exempt |
| `G` | Export outside the EU, free of VAT |
| `O` | Outside the scope of VAT |
| `L` | Canary Islands' IGIC |
| `M` | Ceuta and Melilla's IPSI |
| `B` | Transferred VAT (Italy's split payment) |

### `card.facts[].kind`

What a fact on a document's card is.

| Wartość | Znaczenie |
| --- | --- |
| `deadline` | A date something is due by; its label says what |
| `valid_from` | The day it is valid from |
| `valid_until` | The day it is valid until |
| `reference` | A number naming something else |
| `amount` | An amount |
| `party` | Someone besides its issuer and recipient |
| `date` | Any other date: an inspection, an acceptance |
| `other` | Anything else |

### `worked_out[].field`

The amount worked out, by its path.

| Wartość | Znaczenie |
| --- | --- |
| `totals.net` | BT-109 |
| `totals.tax` | BT-110 |
| `totals.gross` | BT-112 |

### `worked_out[].rule`

How Ocost worked an amount out.

| Wartość | Znaczenie |
| --- | --- |
| `groups` | The VAT groups' sum |
| `net_tax` | Net plus VAT |
| `skonto` | The gross read was the amount less Skonto |
| `payable` | The gross read was what is left to pay |
| `outside` | The net with an amount outside the VAT groups: a deposit, a tip |
| `tip` | The gross read was the amount paid: the bill and its tip, read apart |

### `sources.*.confidence`

How sure Ocost is of a value, from its checks: never a model's grade.

| Wartość | Znaczenie |
| --- | --- |
| `checked` | A check confirmed it, or it came from an e-invoice |
| `read` | Nothing speaks against it |
| `doubt` | A check failed (`why` names it), or its words weren't on its page |

### `checks[].name`

A check Ocost ran in code on what it read.

| Wartość | Suma | Znaczenie |
| --- | --- | --- |
| `total` | tak | A total was read |
| `vat` | tak | A VAT group's VAT is its net × rate (`at` the rate) |
| `vat_net` | tak | The VAT groups' nets add up to the net |
| `vat_tax` | tak | The VAT groups' VAT adds up to the VAT |
| `gross` | tak | Net plus VAT is the gross (the net, with no VAT printed) |
| `payable` | tak | What is left to pay is between nothing and the gross |
| `signs` | tak | No total is negative |
| `deduction` | tak | A deducted invoice's net plus VAT is its gross (`at` which) |
| `deductions` | tak | The gross less the deductions is what is left to pay |
| `quantity` | tak | A delivered quantity is positive, or the line is backordered (`at` the line) |
| `skonto` | tak | A Skonto is plausible: up to 10 %, within a year |
| `line` |  | A line's quantity × price, less its discount, is its net (`at` the line) |
| `lines_net` |  | The lines add up to the net (the gross, priced with VAT) |
| `lines_currency` |  | The lines are in another currency than the totals (`at` it) |
| `vat_lines` |  | A VAT group's net is its lines' (`at` the rate) |
| `line_tax` |  | A line's printed VAT is its net × rate, and its net plus VAT its printed gross (`at` the line) |
| `lines_tax` |  | The lines' printed VAT adds up to their VAT group's (`at` the rate) |
| `iban` |  | The IBAN's check digits hold |
| `vat_id` |  | A VAT ID has its country's format |
| `identifier` |  | A party's identifier has its length and check digit (`at` its scheme: an ЄДРПОУ, a РНОКПП, a NIP) |
| `issued_on` |  | The issue date is neither years ago nor ahead |
| `due_on` |  | The due date isn't before the issue date |
| `service` |  | The service period starts before it ends |
| `valid_until` |  | A quote holds until after its issue date |
| `delivery_on` |  | The delivery date is near the issue date |
| `stated` |  | The amounts stated in a second currency add up |
| `stated_rate` |  | The amounts in both currencies agree at the rate printed, else the ECB's (`at` the rate) |
| `payment_sum` |  | A contract's payment: net plus VAT is its gross (`at` which) |
| `payment_vat` |  | A contract's payment: its VAT is its net × rate |
| `payment_sign` |  | A contract's payment: its amounts are positive |
| `step` |  | A stepped rent's step falls in the term, in order |
| `first_payment` |  | A contract's first payment falls in its term |
| `deposit` |  | A contract's deposit is positive |

### `tax_check.case`

Which German rules an incoming invoice is held to.

| Wartość | Znaczenie |
| --- | --- |
| `standard` | § 14 Abs. 4 UStG: an invoice with VAT |
| `small` | § 33 UStDV: a small amount, up to 250 € |
| `reverse_charge` | § 13b, § 14a Abs. 5 UStG: the business owes the VAT |
| `intra_eu` | § 14a Abs. 3 UStG: an intra-community supply |
| `exempt` | § 14 Abs. 4 Satz 1 Nr. 8 UStG: an exempt supply |

### `tax_check.missing[].item`

What an invoice lacks, or has wrong, for its case.

| Wartość | Znaczenie |
| --- | --- |
| `supplier_name` | The supplier's full name |
| `supplier_address` | The supplier's full address |
| `supplier_tax_id` | The supplier's tax number or VAT ID |
| `recipient_name` | The recipient's full name |
| `recipient_address` | The recipient's full address |
| `recipient_not_us` | It is addressed to someone else than the business |
| `recipient_address_not_ours` | It is addressed to an address that isn't the business's |
| `issued_on` | The issue date |
| `number` | The invoice number |
| `description` | The quantity and kind of the goods or services |
| `service_date` | The day of the supply or service |
| `net` | The net per rate |
| `tax_rate` | The VAT rate |
| `tax_amount` | The VAT |
| `exemption_note` | The note on why it is exempt |
| `reverse_charge_note` | The note that the recipient owes the VAT (Steuerschuldnerschaft des Leistungsempfängers) |
| `intra_eu_note` | The note that it is an intra-community supply |
| `supplier_vat_id` | The supplier's VAT ID |
| `recipient_vat_id` | The recipient's VAT ID |
| `vat_charged` | German VAT charged where the business owes it itself (§ 13b): not deductible, and paying it pays VAT twice |
| `vat_non_payer` | Ukraine: ПДВ charged by a supplier Ukraine's register says is no VAT payer (платник ПДВ): no tax credit for it |
| `supplier_idno` | Moldova: the supplier's IDNO |
| `supplier_vat_code` | Moldova: the supplier's VAT code (cod TVA), where it charges VAT |
| `vat_rate_unknown` | Moldova: a VAT rate other than 20 %, 8 % or 0 % |

### `attention[]`

What a person should look at before booking it.

| Wartość | Znaczenie |
| --- | --- |
| `sums` | A check with `sums: true` failed |
| `outgoing` | The business issued it |
| `possible_duplicate` | An earlier document has its kind, number and seller (`possible_duplicate_of`) |
| `self_billed` | A self-billed invoice (Gutschrift): the buyer issued it |

### `read_with`

How Ocost read it: never a model's or provider's name.

| Wartość | Znaczenie |
| --- | --- |
| `e_invoice` | From its XML, exactly |
| `reader` | From its pages |

### `type_code`

UNCL 1001, od jednej do trzech cyfr. E-faktura może nieść kod, którego tu nie ma. Gdy dokument nie drukuje żadnego, Ocost wpisuje kod jego rodzaju:

| Wartość | Znaczenie |
| --- | --- |
| `380` | Commercial invoice |
| `381` | Credit note |
| `384` | Corrected invoice |
| `389` | Self-billed invoice |
| `326` | Partial invoice |
| `386` | Prepayment invoice |
| `325` | Pro forma invoice |
| `875` | Partial construction invoice |
| `876` | Partial final construction invoice |
| `877` | Final construction invoice |
| `383` | Debit note |
| `393` | Factored invoice |
| `751` | Invoice information for accounting purposes |
| `81` | Credit note related to goods or services |
| `83` | Credit note related to financial adjustments |
| `261` | Self-billed credit note |
| `262` | Consolidated credit note, goods and services |
| `396` | Factored credit note |
| `532` | Forwarder's credit note |

### `sources`

Ścieżki, które wskazują `sources`, `checks[].fields` i `worked_out[].field`, `n` od 0. Późniejsza wersja Ocost może dodać ścieżki:

`number`, `issue_date`, `due_date`, `delivery_date`, `valid_until`, `currency`, `order_reference`, `seller.name`, `buyer.name`, `seller.vat_id`, `buyer.vat_id`, `seller.contact.email`, `buyer.contact.email`, `seller.contact.phone`, `buyer.contact.phone`, `seller.website`, `buyer.website`, `seller.legal_registration_id`, `buyer.legal_registration_id`, `totals.net`, `totals.tax`, `totals.gross`, `totals.payable`, `payment.iban`, `payment.means_code`, `payment.paid_on`, `lines`, `other_parties[n].name`, `deductions[n].gross`

## Zobacz też

- [Jednostki i kody](https://ocost.io/docs/pl/units.md): Listy kodów dokumentu: jednostki UNECE z drukowanymi słowami, waluty i kraje ISO, kategorie VAT, sposoby płatności, rodzaje dokumentów, identyfikatory, ECLASS.
- [Statusy i powody](https://ocost.io/docs/pl/statuses.md): Statusy pliku i powody, dla których nie został odczytany, oraz co zrobić w każdym przypadku.
- [Niemcy](https://ocost.io/docs/pl/germany.md): Niemieckie dokumenty: od Rechnung do Lieferschein według rodzaju, USt-IdNr. i Steuernummer, kategorie VAT, kontrola według § 14 UStG, XRechnung i ZUGFeRD.
- [Dokument OpenAPI](https://ocost.io/docs/openapi.json): Każda trasa, parametr i pole API Ocost, wzięte z jego dokumentu OpenAPI.
- Na ocost.io: [Invoice processing](https://ocost.io/en/product/invoice-processing), [Three-way match](https://ocost.io/en/product/three-way-match), [E-invoicing](https://ocost.io/en/product/e-invoicing)
