# Documentul
> Schema ocost.document.v1 în termenii EN 16931 (se mapează pe UBL și CII): un exemplu, tip și direcție, surse, verificări, versiuni și fiecare câmp și valoare.
>
> Înainte: [Trimiteți și citiți un fișier](https://ocost.io/docs/ro/files.md)

Ocost returnează fiecare document citit ca `ocost.document.v1`. Cereți-l cu `GET /public/v1/files/{file_id}/document` sau `GET /public/v1/documents/{document_id}`. Câmpurile urmează EN 16931, norma din spatele XRechnung, ZUGFeRD și Peppol UBL. Fiecare câmp își numește termenul de business (BT-…) sau grupul (BG-…), deci se poate mapa pe UBL sau CII.

Validați față de [JSON Schema](https://ocost.io/docs/schemas/ocost.document.v1.json) sau generați tipuri din ea. [Câmpuri](#campuri) și [Valori](#valori) de mai jos listează tot ce conține.

## Un exemplu

O factură primită cu două linii la 19 % și 2 % Skonto în 14 zile:

```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"
}
```

## Tip și direcție

Ramificați după `kind`. Acesta grupează tipurile de documente ale Ocost în câteva, precum `invoice` sau `delivery_note`. `kind_detail` numește tipul exact. `type_code` dă codul UNCL 1001 al facturii, precum `380`.

`direction` spune dacă documentul este `incoming` de la un furnizor, `outgoing` de la firma dumneavoastră sau `unsure`. Ocost o deduce din datele dumneavoastră din [Setări › Datele firmei](https://app.ocost.io/settings/company), așa că țineți-le corecte.

## Identificatori din orice țară

Lista `identifiers` a fiecărei părți conține numerele tipărite pentru ea, după `scheme`, precum `UA_EDRPOU`, `UA_RNOKPP`, `UA_IPN` sau `PL_NIP`. Nu este nevoie de niciun șablon. `valid` este `false` când o cifră de control nu se verifică și `null` când schema nu are cifră de control.

Documentele, identificatorii și regulile de TVA ale fiecărei țări au o pagină proprie: [Germania](https://ocost.io/docs/ro/germany.md), [Ucraina](https://ocost.io/docs/ro/ukraine.md), [Regatul Unit](https://ocost.io/docs/ro/uk.md), [Statele Unite](https://ocost.io/docs/ro/us.md) și [Republica Moldova](https://ocost.io/docs/ro/moldova.md).

## Plătită unui factor

Pe o factură a cărei creanță a fost cesionată unui factor (Zession, factoring), `payment.iban` este contul factorului. `payment.assigned_to` numește factorul, iar `payment.iban_holder` titularul contului. `payee` conține factorul, acolo unde Ocost l-a citit ca parte.

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

## Cum sunt scrise valorile

| Valoare | Scrisă ca |
| --- | --- |
| Sume și cantități | Numere JSON exacte în forma cea mai scurtă, precum `1270.92` sau `595`. Cel mult 15 cifre semnificative. Citiți-le ca zecimale înainte de calcule. |
| Cote | Procente, precum `19` sau `5.5`. |
| Date și coduri | ISO 8601 (`2026-11-03`), ISO 4217 (`EUR`), ISO 3166-1 alpha-2 (`DE`), unități UNECE (`HUR`). [Unități și coduri](https://ocost.io/docs/ro/units.md) le listează. |
| Coduri citite greșit | `null`, niciodată textul tipărit. La fel pentru un IBAN sau un BIC. |
| Valori lipsă | `null`, când nu sunt tipărite sau când Ocost nu a fost sigur. Ocost nu ghicește niciodată. Prin MCP, un astfel de câmp este omis. |

## Cât de sigur este Ocost

`sources` spune, pentru fiecare valoare după calea ei, unde a fost citită: `page` și `quote`. `confidence` are una din trei valori:

| Încredere | Semnificație |
| --- | --- |
| `checked` | O verificare a confirmat-o sau provine dintr-o factură electronică. |
| `read` | Nimic nu vorbește împotriva ei. |
| `doubt` | O verificare a eșuat, iar `why` o numește. Sau cuvintele ei nu au fost găsite pe pagina ei. |

`box` marchează valoarea pe pagina ei: `x0`, `y0` (stânga sus) și `x1`, `y1` (dreapta jos), ca fracțiuni ale paginii din colțul ei stânga sus, de la 0 la 1. Pagina este `page` așa cum o arată `GET /public/v1/files/{id}/content`, cu rotația aplicată. Pe textul unui PDF chenarul este exact, pe o scanare îl estimează OCR-ul. Fără un chenar stocat este `null`, iar `quote` este tot ce există.

`checks` listează fiecare verificare pe care Ocost a rulat-o în cod, cu `passed`. Verificările marcate `sums: true` adună sumele. Completați o factură fără ca o persoană să se uite la ea doar când toate acestea au trecut.

`attention` listează ce ar trebui să verifice o persoană înainte de înregistrare, de exemplu un posibil duplicat. `tax_check` conține verificarea unei facturi primite față de legea germană, după cum explică [Germania](https://ocost.io/docs/ro/germany.md#verificarea-facturii).

```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);
// Sumele sunt numere exacte. Calculați cu o bibliotecă zecimală, din String(suma).
console.log(document.number, document.totals.gross, sumsHold);
```

## Versiuni

În v1, Ocost poate adăuga o valoare într-o listă, dar nu redenumește și nu elimină niciodată un câmp sau o valoare. Tratați un `kind` necunoscut ca `other` și nu eșuați niciodată la o valoare necunoscută. O schimbare incompatibilă vine ca `ocost.document.v2` sub `/public/v2`, iar v1 mai rămâne 12 luni.

## Modificări

[Jurnalul modificărilor](https://ocost.io/docs/ro/changelog.md) listează fiecare modificare, cea mai nouă prima.

## Câmpuri

Fiecare câmp, scris din codul Ocost. [JSON Schema](https://ocost.io/docs/schemas/ocost.document.v1.json) conține același lucru. Descrierile sunt acolo în engleză, ca aici.

### `Document`

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

### `TaxRegistration`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `number` | string sau null | Its registration number |
| `date` | date sau null | The day it was registered |

### `Party`

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

### `Address`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `street` | string sau null | BT-35 (seller), BT-50 (buyer) |
| `postal_code` | string sau null | BT-38, BT-53 |
| `city` | string sau null | BT-37, BT-52 |
| `country` | string (`DE`) sau null | BT-40, BT-55: ISO 3166-1 alpha-2 |

### `OtherParty`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `name` | string sau null | BT-27 (seller), BT-44 (buyer) |
| `identifiers` | listă de `PartyIdentifier` | Every identifier printed for it, by scheme (BT-29, BT-46 in any country): an ЄДРПОУ, a РНОКПП, an ІПН, a NIP, … |
| `vat_id` | string sau null | BT-31, BT-48 |
| `tax_registration_id` | string sau null | BT-32: the tax number (Steuernummer) |
| `legal_registration_id` | string sau null | BT-30, BT-47: the register entry (HRB …) |
| `address` | `Address` sau null | BG-5, BG-8 |
| `contact` | `Contact` sau null | BG-6, BG-9 |
| `website` | string sau null | As printed: a host, with or without its scheme |
| `role` | enumerare, [Valori](#valori) | What it is to the document |
| `printed_role` | string sau null | The words printed for its role |

### `Payment`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `means_code` | enumerare, [Valori](#valori) sau null | BT-81, UNCL 4461; null when it doesn't say or it was paid already |
| `means` | enumerare, [Valori](#valori) sau null | The same, as a word |
| `iban` | string (`DE02120300000000202051`) sau null | BT-84, without spaces |
| `bic` | string (`BYLADEM1001`) sau null | BT-86 |
| `iban_holder` | string sau null | BT-85: the holder of `iban`, as printed |
| `assigned_to` | `Factor` sau null | The factor its assignment note (Abtretung, Zession, factoring) names; `iban` is then the factor's |
| `terms` | string sau null | BT-20, as printed |
| `net_days` | integer sau null | The days the terms give to pay in full from the issue date |
| `paid_on` | date sau null | The day it says it was paid or charged, where printed |

### `EarlyPaymentDiscount`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `days` | integer |  |
| `percent` | zecimal | 2 for 2 % |
| `base_amount` | zecimal sau null | What it is taken off, where printed; null: the amount due |
| `due_date` | date sau null | The last day for it: the issue date plus `days` |

### `Totals`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `net` | zecimal sau null | BT-109 |
| `tax` | zecimal sau null | BT-110 |
| `gross` | zecimal sau null | BT-112 |
| `payable` | zecimal sau 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`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `category` | enumerare, [Valori](#valori) sau null | BT-118 |
| `rate` | zecimal sau null | BT-119, percent: 19 |
| `taxable_amount` | zecimal | BT-116 |
| `tax_amount` | zecimal | BT-117 |
| `exemption_reason` | string sau null | BT-120 |

### `Line`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `id` | string | BT-126: its position |
| `name` | string | BT-153 |
| `seller_item_id` | string sau null | BT-155: the article number |
| `standard_item_id` | string sau null | BT-157: the GTIN (scheme 0160) |
| `quantity` | zecimal sau null | BT-129 |
| `unit` | string (`C62`) sau null | BT-130: UNECE Rec 20 (C62, HUR, KGM) or Rec 21 (XCT); null when none is printed or it is no code |
| `price` | zecimal sau null | BT-146: the net price |
| `base_quantity` | zecimal sau null | BT-149: how many units `price` is for; null: one |
| `net_amount` | zecimal sau null | BT-131 |
| `discount_percent` | zecimal sau null | The line's discount: 5 |
| `vat_category` | enumerare, [Valori](#valori) sau null | BT-151 |
| `vat_rate` | zecimal sau null | BT-152, percent |
| `tax_amount` | zecimal sau null | The line's VAT, only as printed on it; null when it prints none |
| `gross_amount` | zecimal sau null | The line's total with VAT, only as printed on it; null when it prints none |
| `ordered_quantity` | zecimal sau null | A delivery note's |
| `backordered_quantity` | zecimal sau null | Still to come |
| `batch` | string sau null | Its batch (Charge), as printed |
| `pzn` | string sau null | A medicine's PZN |
| `attributes` | hartă de string | What it is, as printed: colour, size, material, brand, … |

### `Deduction`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `number` | string sau null |  |
| `issue_date` | date sau null |  |
| `net` | zecimal sau null |  |
| `tax` | zecimal sau null |  |
| `gross` | zecimal sau null |  |

### `Card`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `title` | string sau null |  |
| `summary` | string sau null |  |
| `facts` | listă de `Fact` |  |

### `WorkedOut`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `field` | enumerare, [Valori](#valori) | Its path in this document |
| `printed` | zecimal sau null | What was read |
| `rule` | enumerare, [Valori](#valori) | How Ocost worked an amount out. |

### `Source`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `page` | integer sau null | Where it was read: the file's page, from 1 |
| `quote` | string sau null | The words it was read from |
| `box` | `Box` sau null | Its rectangle on `page`; null when Ocost kept none (then `quote` is all there is) |
| `confidence` | enumerare, [Valori](#valori) | How sure Ocost is of a value, from its checks: never a model's grade. |
| `why` | string sau null | For a doubt: the failed check's `name` |

### `Check`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `name` | enumerare, [Valori](#valori) | 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` | listă de string (`totals.gross`) | The paths it is about, as `sources` names them |
| `at` | string sau null | The rate or the line it is about |

### `TaxCheck`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `case` | enumerare, [Valori](#valori) | Which German rules an incoming invoice is held to. |
| `missing` | listă de `TaxItem` |  |

### `PartyIdentifier`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `scheme` | enumerare, [Valori](#valori) | 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 sau null | Its length and check digit hold; false: in doubt, a misread (never matched on); null: its scheme has no check |

### `Contact`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `email` | string sau null | BT-43, BT-58: an address as printed |
| `phone` | string sau null | BT-42, BT-57: as printed |

### `Factor`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `name` | string | As the assignment note prints it |

### `Fact`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `label` | string | What it is, in the document's words |
| `kind` | enumerare, [Valori](#valori) | What a fact on a document's card is. |
| `date` | date sau null |  |
| `amount` | zecimal sau null |  |
| `currency` | string (`EUR`) sau null | ISO 4217, of `amount` |
| `number` | zecimal sau null |  |
| `text` | string sau null |  |
| `page` | integer sau null |  |

### `Box`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `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`

| Câmp | Tip | Semnificație |
| --- | --- | --- |
| `item` | enumerare, [Valori](#valori) | 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 |

## Valori

Fiecare listă de valori, scrisă din codul Ocost. [JSON Schema](https://ocost.io/docs/schemas/ocost.document.v1.json) și [referința API](https://ocost.io/docs/openapi.json) conțin același lucru, semnificațiile în engleză. O versiune ulterioară Ocost poate adăuga o valoare în v1. Tratați un `kind` necunoscut ca `other` și lăsați deoparte orice altă valoare necunoscută. În v1 nicio valoare nu este redenumită sau eliminată.

### `kind`

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

| Valoare | Semnificație |
| --- | --- |
| `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).

Fiecare `kind_detail`, după `kind`-ul care este:

| 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.

| Valoare | Semnificație |
| --- | --- |
| `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.

| Valoare | Semnificație |
| --- | --- |
| `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.

| Valoare | Semnificație |
| --- | --- |
| `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.

| Valoare | Semnificație |
| --- | --- |
| `58` | SEPA credit transfer |
| `59` | SEPA direct debit |
| `48` | Bank card |

### `payment.means`

How it is paid, as a word.

| Valoare | Semnificație |
| --- | --- |
| `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.

| Valoare | Semnificație |
| --- | --- |
| `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.

| Valoare | Semnificație |
| --- | --- |
| `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.

| Valoare | Semnificație |
| --- | --- |
| `totals.net` | BT-109 |
| `totals.tax` | BT-110 |
| `totals.gross` | BT-112 |

### `worked_out[].rule`

How Ocost worked an amount out.

| Valoare | Semnificație |
| --- | --- |
| `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.

| Valoare | Semnificație |
| --- | --- |
| `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.

| Valoare | Sumă | Semnificație |
| --- | --- | --- |
| `total` | da | A total was read |
| `vat` | da | A VAT group's VAT is its net × rate (`at` the rate) |
| `vat_net` | da | The VAT groups' nets add up to the net |
| `vat_tax` | da | The VAT groups' VAT adds up to the VAT |
| `gross` | da | Net plus VAT is the gross (the net, with no VAT printed) |
| `payable` | da | What is left to pay is between nothing and the gross |
| `signs` | da | No total is negative |
| `deduction` | da | A deducted invoice's net plus VAT is its gross (`at` which) |
| `deductions` | da | The gross less the deductions is what is left to pay |
| `quantity` | da | A delivered quantity is positive, or the line is backordered (`at` the line) |
| `skonto` | da | 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.

| Valoare | Semnificație |
| --- | --- |
| `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.

| Valoare | Semnificație |
| --- | --- |
| `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.

| Valoare | Semnificație |
| --- | --- |
| `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.

| Valoare | Semnificație |
| --- | --- |
| `e_invoice` | From its XML, exactly |
| `reader` | From its pages |

### `type_code`

UNCL 1001, una până la trei cifre. O factură electronică poate purta un cod care lipsește aici. Unde documentul nu tipărește niciunul, Ocost scrie codul tipului său:

| Valoare | Semnificație |
| --- | --- |
| `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`

Căile pe care le numesc `sources`, `checks[].fields` și `worked_out[].field`, `n` de la 0. O versiune ulterioară Ocost poate adăuga căi:

`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`

## Vezi și

- [Unități și coduri](https://ocost.io/docs/ro/units.md): Listele de coduri ale documentului: unități UNECE cu cuvintele lor tipărite, monede și țări ISO, categorii de TVA, modalități de plată, tipuri de documente, identificatori, ECLASS.
- [Stări și motive](https://ocost.io/docs/ro/statuses.md): Stările unui fișier și motivele pentru care nu a fost citit, și ce faceți în fiecare caz.
- [Germania](https://ocost.io/docs/ro/germany.md): Documente germane: de la Rechnung la Lieferschein după tip, USt-IdNr. și Steuernummer, categoriile de TVA, verificarea § 14 UStG, XRechnung și ZUGFeRD.
- [Documentul OpenAPI](https://ocost.io/docs/openapi.json): Fiecare rută, parametru și câmp al API-ului Ocost, din documentul său OpenAPI.
- Pe 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)
