Waliduj względem JSON Schema albo generuj z niego typy. Pola i Wartości poniżej wymieniają wszystko, co zawiera.
Przykład
Faktura przychodząca z dwiema pozycjami po 19 % i 2 % Skonto w ciągu 14 dni:
{
"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, 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, Ukraina, Wielka Brytania, Stany Zjednoczone i Mołdawia.
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ę.
{
"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 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.
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"]
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 wymienia każdą zmianę, od najnowszej.
Pola
Każde pole, wypisane z kodu Ocost. JSON Schema 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 | What a document is, grouped so an integrator branches on few; the exact kind is kind_detail. |
kind_detail | wyliczenie, Wartości | The exact kind, one of Ocost's document types, for information |
direction | wyliczenie, Wartości | 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 | 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 | 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 | 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 lub null | BT-81, UNCL 4461; null when it doesn't say or it was paid already |
means | wyliczenie, Wartości 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 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 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 | Its path in this document |
printed | liczba dziesiętna lub null | What was read |
rule | wyliczenie, Wartości | 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 | 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 | 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 | Which German rules an incoming invoice is held to. |
missing | lista TaxItem | |
PartyIdentifier
| Pole | Typ | Znaczenie |
|---|
scheme | wyliczenie, Wartości | 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 | 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 | 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 i dokumentacja API 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