Referencia de la API

https://api.ocost.io/public/v1

Ocost API 1 · El documento OpenAPI

Las descripciones de la referencia vienen del documento OpenAPI de la API, en inglés.

Rutas

get/public/v1/businesses

List Businesses

The businesses this key reaches: its own first, then the others of its group its owner gave it, by name. A request names the one it acts in with Ocost-Business (docs/specs/074 › API keys across companies). Any scope; 60 calls a minute.

Parámetros

  • Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403 urn:ocost:key:business otherwise). Without it, the business the key was made in; a file sent without it by a key that reaches several goes to the company its document names (routed_by), and a file is found in whichever of them it went to.

Respuestas

get/public/v1/documents/{document_id}

Get Document

One document as ocost.document.v1.

Parámetros

  • document_idpathstring (uuid)obligatorioA document's id: from a file's documents or a search result
  • Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403 urn:ocost:key:business otherwise). Without it, the business the key was made in; a file sent without it by a key that reaches several goes to the company its document names (routed_by), and a file is found in whichever of them it went to.

Respuestas

get/public/v1/files

List Files

The files changed at or after updated_since, oldest change first, of the statuses asked for, carrying external_ref when it is given: what a connector polls. The next page is next_cursor's; with no more, keep the last cursor and ask with it later for what changed since. A change made as a page is read comes on a later one. A key that reaches several businesses of a group and names none (Ocost-Business) lists its own business's files and those it sent that went to the others (business_id says where each is).

Parámetros

  • statusqueryFileStatus[] | nullOnly files of these statuses; repeat it for several
  • updated_sincequerystring (date-time) | nullFiles changed at or after this time (ISO 8601)
  • external_refquerystring | nullOnly the files carrying this reference among their external_refs (exactly)
  • cursorquerystring | nullnext_cursor of the page before
  • limitqueryintegerFiles per page
  • business_idquerystring (uuid) | nullOnly the files in this business, one the key reaches (GET /businesses)
  • Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403 urn:ocost:key:business otherwise). Without it, the business the key was made in; a file sent without it by a key that reaches several goes to the company its document names (routed_by), and a file is found in whichever of them it went to.

Respuestas

post/public/v1/files

Send File

Sends a file to be read (multipart, field file): 202 with the file, received, when it is new; 200 with the file as it is when the same bytes were sent before (they are read and counted once; a new external_ref is kept beside the ones before, in external_refs). Each answer says the month's documents left in X-Ocost-Documents-Left. 413 past 25 MB, 415 for a kind Ocost doesn't read (an archive among them), 409 when the same bytes are a file of the business the key doesn't see (a person's own upload), 422 for a 51st reference.

Parámetros

  • Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403 urn:ocost:key:business otherwise). Without it, the business the key was made in; a file sent without it by a key that reaches several goes to the company its document names (routed_by), and a file is found in whichever of them it went to.

Cuerpo de la solicitud · multipart/form-data

  • external_refstringYour own id for it (an Odoo bill's), kept and given back; the same bytes sent again with another keep it too (external_refs, up to 50)
  • filestring (binary)obligatorioA PDF, an image (JPEG, PNG, TIFF, WebP), a Word file (.docx, .doc) or an e-invoice's XML (XRechnung, UBL, CII); at most 25 MB
  • namestringIts file name; the upload's own when left out

Respuestas

get/public/v1/files/{file_id}

Get File

A file: its status, why it isn't read where it isn't, and the documents it holds once it is; the business it is in, and how that was chosen.

Parámetros

  • file_idpathstring (uuid)obligatorioThe file's id, as POST /files answered it
  • Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403 urn:ocost:key:business otherwise). Without it, the business the key was made in; a file sent without it by a key that reaches several goes to the company its document names (routed_by), and a file is found in whichever of them it went to.

Respuestas

patch/public/v1/files/{file_id}

Assign File

Says which business a file waiting for its company (needs_company) belongs to: one the key reaches (403 otherwise; GET /businesses). It is read on there, counted there, and found by its id as before; Ocost's question about it goes. The same bytes kept there already: that file is the answer, and this one goes. 409 for a file that doesn't wait for its company.

Parámetros

  • file_idpathstring (uuid)obligatorioThe file's id, as POST /files answered it
  • Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403 urn:ocost:key:business otherwise). Without it, the business the key was made in; a file sent without it by a key that reaches several goes to the company its document names (routed_by), and a file is found in whichever of them it went to.

Cuerpo de la solicitud · application/json

Respuestas

delete/public/v1/files/{file_id}

Delete File

Erases the file for good, at once: its documents, their lines, sources and parties, its passages and its reading, and the original in storage. 409 while it is being read (urn:ocost:file:reading), and while Ocost still needs it as Files would keep it: an invoice paid, matched or exported, a bank statement, an open question, a project's file (urn:ocost:file:linked, the reason in detail); 404 after.

Parámetros

  • file_idpathstring (uuid)obligatorioThe file's id, as POST /files answered it
  • Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403 urn:ocost:key:business otherwise). Without it, the business the key was made in; a file sent without it by a key that reaches several goes to the company its document names (routed_by), and a file is found in whichever of them it went to.

Respuestas

get/public/v1/files/{file_id}/content

Get File Content

The original's bytes, as they were sent.

Parámetros

  • file_idpathstring (uuid)obligatorioThe file's id, as POST /files answered it
  • Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403 urn:ocost:key:business otherwise). Without it, the business the key was made in; a file sent without it by a key that reaches several goes to the company its document names (routed_by), and a file is found in whichever of them it went to.

Respuestas

get/public/v1/files/{file_id}/document

Get File Document

The file's first document as ocost.document.v1: what a bill is filled from. A file holding several lists them all (documents), each at /documents/{id}. 404 while it has none.

Parámetros

  • file_idpathstring (uuid)obligatorioThe file's id, as POST /files answered it
  • Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403 urn:ocost:key:business otherwise). Without it, the business the key was made in; a file sent without it by a key that reaches several goes to the company its document names (routed_by), and a file is found in whichever of them it went to.

Respuestas

Esquemas

Address

  • citystring | nullBT-37, BT-52
  • countrystring | nullBT-40, BT-55: ISO 3166-1 alpha-2
  • postal_codestring | nullBT-38, BT-53
  • streetstring | nullBT-35 (seller), BT-50 (buyer)

Attention

What a person should look at before booking it.

  • 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

"sums" | "outgoing" | "possible_duplicate" | "self_billed"

Box

Where a value stands on its page: a rectangle in fractions of the page from its top-left corner (0 to 1, so any rendering's size), the page as GET /files/{id}/content's pages show it (a PDF's /Rotate, an image's EXIF orientation applied). From a PDF's own words exact; on a scan or a photo, the OCR's line and characters, an estimate.

  • x0numberobligatorioIts left edge, from the page's left
  • x1numberobligatorioIts right edge, from the page's left
  • y0numberobligatorioIts top edge, from the page's top
  • y1numberobligatorioIts bottom edge, from the page's top

Candidate

A company of the group a file may belong to (needs_company).

  • business_idstring (uuid)obligatorioWhat PATCH names
  • namestringobligatorio
  • whyCandidateWhyobligatorio

CandidateWhy

Why a company may be the one a file belongs to.

  • vat_id: Its VAT ID is on the document
  • tax_number: Its tax number is on the document
  • edrpou: Its ЄДРПОУ or РНОКПП is on the document
  • register: Its register number and court are on the document
  • iban: Its account is the one the document asks to be paid into
  • name: Its name or address alone, which never decides
  • home: The key's own business

"vat_id" | "tax_number" | "edrpou" | "register" | "iban" | "name" | "home"

Card

What a document without fields of its own says: a title, a summary and its facts (deadlines first).

  • factsFact[]obligatorio
  • summarystring | null
  • titlestring | null

Check

A check Ocost ran in code, and whether it passed.

  • atstring | nullThe rate or the line it is about
  • fieldsstring[]obligatorioThe paths it is about, as sources names them
  • nameCheckNameobligatorioWhat it checked; sums says whether it is one of the sums
  • passedbooleanobligatorio
  • sumsbooleanobligatorioOne of the sums (total, vat, vat_net, vat_tax, gross, payable, signs, skonto, deduction, deductions, quantity): fill a bill only when all pass

CheckName

A check Ocost ran in code on what it read.

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

"total" | "vat" | "vat_net" | "vat_tax" | "gross" | "payable" | "signs" | "deduction" | "deductions" | "quantity" | "skonto" | "line" | "lines_net" | "lines_currency" | "vat_lines" | "line_tax" | "lines_tax" | "iban" | "vat_id" | "identifier" | "issued_on" | "due_on" | "service" | "valid_until" | "delivery_on" | "stated" | "stated_rate" | "payment_sum" | "payment_vat" | "payment_sign" | "step" | "first_payment" | "deposit"

Confidence

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

  • 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

"checked" | "read" | "doubt"

Contact

  • emailstring | nullBT-43, BT-58: an address as printed
  • phonestring | nullBT-42, BT-57: as printed

Deduction

A final invoice's: an earlier invoice it takes off.

  • grossnumber (decimal) | null
  • issue_datestring (date) | null
  • netnumber (decimal) | null
  • numberstring | null
  • taxnumber (decimal) | null

Direction

Whether the business received or issued it.

  • incoming: To the business: a supplier's
  • outgoing: The business issued it
  • unsure: Its parties don't say

"incoming" | "outgoing" | "unsure"

Document

ocost.document.v1: one document as Ocost read it.

  • attentionAttention[]obligatorio
  • buyerParty | nullBG-7
  • buyer_referencestring | nullBT-10
  • cardCard | null
  • checksCheck[]obligatorio
  • contract_referencestring | nullBT-12: the contract it refers to (an act's)
  • currencystring | nullBT-5, ISO 4217
  • deductionsDeduction[]obligatorio
  • deliver_toAddress | nullBG-15
  • delivery_datestring (date) | nullBT-72
  • directionDirectionobligatorio
  • due_datestring (date) | nullBT-9
  • early_payment_discountsEarlyPaymentDiscount[]obligatorio
  • file_idstring (uuid)obligatorioThe file it is in
  • idstring (uuid)obligatorioThe document
  • invoicing_period_endstring (date) | nullBT-74
  • invoicing_period_startstring (date) | nullBT-73
  • issue_datestring (date) | nullBT-2
  • kindKindobligatorio
  • kind_detailKindDetailobligatorio
  • linesLine[]obligatorio
  • numberstring | nullBT-1
  • order_referencestring | nullBT-13
  • order_referencesstring[]obligatorioEvery order it names
  • other_partiesOtherParty[]obligatorioEvery other party named
  • pagesinteger[]obligatorioIts pages in the file, from 1
  • payeeParty | nullBG-10: when not the seller
  • paymentPaymentobligatorio
  • possible_duplicate_ofstring (uuid) | nullAn earlier document of the same kind, number and seller
  • preceding_invoicestring | nullBT-25; a tax invoice's: the invoice or act it is for
  • read_withReadWithobligatorio
  • schema"ocost.document.v1"Always this
  • sellerParty | nullBG-4
  • sourcesobjectobligatorioPer value, by its path: 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; a later Ocost may add paths
  • tax_checkTaxCheck | null
  • tax_registrationTaxRegistration | nullA tax invoice's registration, where printed
  • totalsTotalsobligatorio
  • type_codestring | nullBT-3, UNCL 1001: 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; an e-invoice may carry another
  • valid_untilstring (date) | nullA quote's
  • vat_breakdownVatGroup[]obligatorio
  • worked_outWorkedOut[]obligatorio

DocumentRef

One document a file holds.

  • idstring (uuid)obligatorio
  • kindKindobligatorio
  • numberstring | nullBT-1, as printed
  • pagesinteger[]obligatorioIts pages in the file, from 1

EarlyPaymentDiscount

Skonto: XRechnung's #SKONTO# in BT-20.

  • base_amountnumber (decimal) | nullWhat it is taken off, where printed; null: the amount due
  • daysintegerobligatorio
  • due_datestring (date) | nullThe last day for it: the issue date plus days
  • percentnumber (decimal)obligatorio2 for 2 %

Fact

  • amountnumber (decimal) | null
  • currencystring | nullISO 4217, of amount
  • datestring (date) | null
  • kindFactKindobligatorio
  • labelstringobligatorioWhat it is, in the document's words
  • numbernumber (decimal) | null
  • pageinteger | null
  • textstring | null

FactKind

What a fact on a document's card is.

  • 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

"deadline" | "valid_from" | "valid_until" | "reference" | "amount" | "party" | "date" | "other"

Factor

Who the receivable is assigned or sold to.

  • namestringobligatorioAs the assignment note prints it

FieldError

One invalid field of a request.

  • locstring | integer[]obligatorio
  • msgstringobligatorio
  • typestringobligatorio

FileCompany

The business a file waiting for its company belongs to.

  • business_idstring (uuid)obligatorioOne of the businesses the key reaches (GET /businesses)

FileStatus

How far Ocost is with a file.

  • received: Stored, not read yet
  • reading: Being read
  • read: Read: documents lists what it holds
  • not_read: Stored, not read; reason says why
  • failed: Ocost couldn't read it; reason says why
  • needs_company: Read, but its document names none of your group's companies or several: candidates lists them; PATCH it with the business_id it belongs to, or someone answers in Ocost

"received" | "reading" | "read" | "not_read" | "failed" | "needs_company"

FoundBy

How a passage was found.

  • words: By its words
  • meaning: By its meaning
  • both: By both

"words" | "meaning" | "both"

FoundFact

  • labelstringobligatorio
  • textstring | null

Hit

  • found_byFoundByobligatorio
  • highlightsany[][]obligatorioWhere the words are in text: [start, end) character ranges
  • pageintegerobligatorio
  • textstringobligatorio

IdentifierScheme

What an identifier of a party is.

  • 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

"UA_EDRPOU" | "UA_RNOKPP" | "UA_IPN" | "EU_VAT" | "DE_STNR" | "COMMERCIAL_REGISTER" | "PL_NIP" | "PL_REGON" | "PL_KRS" | "GB_CRN" | "FR_SIREN" | "FR_SIRET" | "CZ_ICO" | "RO_CUI" | "NO_ORGNR" | "FI_YTUNNUS" | "US_EIN" | "US_STATE_FILE" | "MD_IDNO" | "MD_IDNP" | "MD_VAT" | "OTHER"

Kind

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

  • 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

"invoice" | "credit_note" | "invoice_correction" | "receipt" | "pro_forma" | "delivery_note" | "order" | "order_confirmation" | "quote" | "contract" | "statement" | "payment_reminder" | "tax_invoice" | "other"

KindDetail

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

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

KnownCompany

A company of the group a refusal or an answer is about (docs/specs/073 › The same company): found by its name only, so a person decides.

  • idstringobligatorio
  • namestringobligatorio
  • numbersstring[]obligatorioIts numbers as Ocost keeps them

Line

BG-25.

  • attributes{ [key]: string }obligatorioWhat it is, as printed: colour, size, material, brand, …
  • backordered_quantitynumber (decimal) | nullStill to come
  • base_quantitynumber (decimal) | nullBT-149: how many units price is for; null: one
  • batchstring | nullIts batch (Charge), as printed
  • discount_percentnumber (decimal) | nullThe line's discount: 5
  • gross_amountnumber (decimal) | nullThe line's total with VAT, only as printed on it; null when it prints none
  • idstringobligatorioBT-126: its position
  • namestringobligatorioBT-153
  • net_amountnumber (decimal) | nullBT-131
  • ordered_quantitynumber (decimal) | nullA delivery note's
  • pricenumber (decimal) | nullBT-146: the net price
  • pznstring | nullA medicine's PZN
  • quantitynumber (decimal) | nullBT-129
  • seller_item_idstring | nullBT-155: the article number
  • standard_item_idstring | nullBT-157: the GTIN (scheme 0160)
  • tax_amountnumber (decimal) | nullThe line's VAT, only as printed on it; null when it prints none
  • unitstring | nullBT-130: UNECE Rec 20 (C62, HUR, KGM) or Rec 21 (XCT); null when none is printed or it is no code
  • vat_categoryVatCategory | nullBT-151
  • vat_ratenumber (decimal) | nullBT-152, percent

Means

How it is paid, as a word.

  • 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)

"transfer" | "direct_debit" | "card" | "already_paid"

MeansCode

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

  • 58: SEPA credit transfer
  • 59: SEPA direct debit
  • 48: Bank card

"58" | "59" | "48"

OtherParty

  • addressAddress | nullBG-5, BG-8
  • contactContact | nullBG-6, BG-9
  • identifiersPartyIdentifier[]Every identifier printed for it, by scheme (BT-29, BT-46 in any country): an ЄДРПОУ, a РНОКПП, an ІПН, a NIP, …
  • legal_registration_idstring | nullBT-30, BT-47: the register entry (HRB …)
  • namestring | nullBT-27 (seller), BT-44 (buyer)
  • printed_rolestring | nullThe words printed for its role
  • rolePartyRoleobligatorioWhat it is to the document
  • tax_registration_idstring | nullBT-32: the tax number (Steuernummer)
  • vat_idstring | nullBT-31, BT-48
  • websitestring | nullAs printed: a host, with or without its scheme

Party

  • addressAddress | nullBG-5, BG-8
  • contactContact | nullBG-6, BG-9
  • identifiersPartyIdentifier[]Every identifier printed for it, by scheme (BT-29, BT-46 in any country): an ЄДРПОУ, a РНОКПП, an ІПН, a NIP, …
  • legal_registration_idstring | nullBT-30, BT-47: the register entry (HRB …)
  • namestring | nullBT-27 (seller), BT-44 (buyer)
  • tax_registration_idstring | nullBT-32: the tax number (Steuernummer)
  • vat_idstring | nullBT-31, BT-48
  • websitestring | nullAs printed: a host, with or without its scheme

PartyIdentifier

  • schemeIdentifierSchemeobligatorio
  • validboolean | nullIts length and check digit hold; false: in doubt, a misread (never matched on); null: its scheme has no check
  • valuestringobligatorioDigits only for the schemes of digits, a VAT ID without spaces, any other as printed

PartyRole

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

  • 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

"seller" | "buyer" | "invoicee" | "service_recipient" | "payer" | "payee" | "ship_to" | "carrier" | "factor" | "debtor" | "guarantor" | "landlord" | "tenant" | "subtenant" | "contractor" | "subcontractor" | "principal" | "agent" | "insurer" | "policyholder" | "other"

Payment

BG-16.

  • assigned_toFactor | nullThe factor its assignment note (Abtretung, Zession, factoring) names; iban is then the factor's
  • bicstring | nullBT-86
  • ibanstring | nullBT-84, without spaces
  • iban_holderstring | nullBT-85: the holder of iban, as printed
  • meansMeans | nullThe same, as a word
  • means_codeMeansCode | nullBT-81, UNCL 4461; null when it doesn't say or it was paid already
  • net_daysinteger | nullThe days the terms give to pay in full from the issue date
  • paid_onstring (date) | nullThe day it says it was paid or charged, where printed
  • termsstring | nullBT-20, as printed

Problem

RFC 9457 problem details, with errors for invalid fields.

  • companyKnownCompany | nullreason same_name: the group's company of that name
  • detailstring | null
  • errorsFieldError[] | null
  • instancestring | null
  • reasonstring | nullRead-only (type urn:ocost:read-only, docs/specs/056): why, trial_ended, unpaid or ended; same_name: a company added without a number whose name a company of the group has (company)
  • renews_onstring (date) | nullA month's limit used (type urn:ocost:limit:<kind>): the day it renews
  • statusintegerobligatorio
  • titlestringobligatorio
  • typestring

PublicBusiness

  • idstring (uuid)obligatorioWhat Ocost-Business names
  • namestringobligatorio
  • ownbooleanobligatorioThe business the key was made in

PublicBusinesses

  • businessesPublicBusiness[]obligatorioThe key's own business first, then the group's others it reaches, by name

PublicFile

A file sent, and how far Ocost is with it.

  • business_idstring (uuid)obligatorioThe business it is in: the key's own, the one the request named, or the company its document names
  • candidatesCandidate[]For needs_company: the companies it may belong to
  • content_typestringobligatorio
  • created_atstring (date-time)obligatorio
  • documentsDocumentRef[]obligatorioOnce read: what it holds
  • external_refstring | nullYour own id for it, as first sent
  • external_refsstring[]obligatorioEvery id you sent with these bytes, the first first, each once; up to 50
  • idstring (uuid)obligatorio
  • namestringobligatorio
  • pagesinteger | nullIts pages, once counted
  • pages_readinteger | nullThe first pages read of a file longer than Ocost reads; null: all of them
  • reasonReason | nullWhy it is not_read or failed
  • renews_onstring (date) | nullFor reason: limit: the day the month's documents renew; it is read then by itself
  • routed_byRoutedBy | nullHow that business was chosen; null while its document is still being read, for a file not sent through the API, and while it is needs_company
  • sha256stringobligatorioThe bytes' SHA-256, hex: the same bytes are one file; empty for a file Ocost made itself before it is hashed
  • size_bytesintegerobligatorio
  • statusFileStatusobligatorio
  • updated_atstring (date-time)obligatorio

PublicFiles

  • filesPublicFile[]obligatorioOldest change first
  • morebooleanobligatorioMore pages are there now: ask again at once
  • next_cursorstring | nullAsk with this as cursor for the next page, and later for what changed since; null when nothing was listed yet

ReadWith

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

  • e_invoice: From its XML, exactly
  • reader: From its pages

"e_invoice" | "reader"

Reason

Why a file is not_read or failed.

  • limit: The month's documents are used up; read on renews_on
  • model_off: This business may not have PDFs and images read; e-invoices still are
  • nothing_found: No document in it
  • too_large: Too many pages or too large an image
  • damaged: Not a file Ocost can open
  • unavailable: No reading service answered for a day; send it again
  • failed: Reading failed
  • other: Any other reason

"limit" | "model_off" | "nothing_found" | "too_large" | "damaged" | "unavailable" | "failed" | "other"

RoutedBy

How the business a file is in was chosen.

  • header: The request named it (Ocost-Business)
  • vat_id: Its document names that company's VAT ID (or ІПН, NIP)
  • tax_number: Its document names that company's tax number
  • edrpou: Its document names that company's ЄДРПОУ or РНОКПП
  • register: Its document names that company's register number and court
  • iban: Its document asks to be paid into that company's account
  • home: The key's own business: its document names no other of the group
  • person: Chosen after Ocost asked, in Ocost or with PATCH

"header" | "vat_id" | "tax_number" | "edrpou" | "register" | "iban" | "home" | "person"

SearchMeaning

Whether search by meaning answered.

  • available: It did
  • unavailable: The index is building or its model unreachable; the words still answer

"available" | "unavailable"

SearchResult

  • buyerstring | nullAs read
  • currencystring | null
  • document_idstring (uuid) | nullNull for a file without one
  • document_urlstring | nullThe document, in this API
  • factsFoundFact[]obligatorioIts card's facts that have the words
  • file_idstring (uuid)obligatorio
  • file_namestringobligatorio
  • file_urlstringobligatorioThe file, in this API
  • grossnumber (decimal) | null
  • issue_datestring (date) | null
  • kindKind | null
  • numberstring | null
  • pagesinteger[]obligatorio
  • passagesHit[]obligatorioAt most 5, best first
  • sellerstring | nullAs read

SearchResults

  • meaningSearchMeaningobligatorio
  • resultsSearchResult[]obligatorio
  • totalintegerobligatorioHow many matched, up to the pool's 300
  • truncatedbooleanobligatorioMore matched than the pool holds

Source

Where a value was read, and how sure Ocost is of it.

  • boxBox | nullIts rectangle on page; null when Ocost kept none (then quote is all there is)
  • confidenceConfidenceobligatorio
  • pageinteger | nullWhere it was read: the file's page, from 1
  • quotestring | nullThe words it was read from
  • whystring | nullFor a doubt: the failed check's name

TaxCase

Which German rules an incoming invoice is held to.

  • 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

"standard" | "small" | "reverse_charge" | "intra_eu" | "exempt"

TaxCheck

An incoming invoice's § 14 UStG check (Germany's rules).

TaxItem

  • at_stakebooleanobligatorioMissing, it costs the input VAT deduction
  • itemTaxItemKindobligatorio
  • lawstringobligatorioThe paragraph that asks for it

TaxItemKind

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

  • 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 %

"supplier_name" | "supplier_address" | "supplier_tax_id" | "recipient_name" | "recipient_address" | "recipient_not_us" | "recipient_address_not_ours" | "issued_on" | "number" | "description" | "service_date" | "net" | "tax_rate" | "tax_amount" | "exemption_note" | "reverse_charge_note" | "intra_eu_note" | "supplier_vat_id" | "recipient_vat_id" | "vat_charged" | "vat_non_payer" | "supplier_idno" | "supplier_vat_code" | "vat_rate_unknown"

TaxRegistration

Where the tax authority registered a tax invoice (Ukraine's ЄРПН).

  • datestring (date) | nullThe day it was registered
  • numberstring | nullIts registration number

Totals

BG-22.

  • grossnumber (decimal) | nullBT-112
  • netnumber (decimal) | nullBT-109
  • payablenumber (decimal) | nullBT-115: what is left to pay; null when it is the gross
  • prices_include_vatbooleanobligatorioIts lines' prices and amounts include VAT (a receipt)
  • taxnumber (decimal) | nullBT-110

VatCategory

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

  • 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)

"S" | "Z" | "E" | "AE" | "K" | "G" | "O" | "L" | "M" | "B"

VatGroup

BG-23.

  • categoryVatCategory | nullBT-118
  • exemption_reasonstring | nullBT-120
  • ratenumber (decimal) | nullBT-119, percent: 19
  • tax_amountnumber (decimal)obligatorioBT-117
  • taxable_amountnumber (decimal)obligatorioBT-116

WorkedOut

An amount Ocost worked out because the one read can't be it.

WorkedOutField

The amount worked out, by its path.

  • totals.net: BT-109
  • totals.tax: BT-110
  • totals.gross: BT-112

"totals.net" | "totals.tax" | "totals.gross"

WorkedOutRule

How Ocost worked an amount out.

  • 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

"groups" | "net_tax" | "skonto" | "payable" | "outside" | "tip"

Véase también