Dokumentacja API
https://api.ocost.io/public/v1
Ocost API 1 · Dokument OpenAPI
Opisy w dokumentacji pochodzą z dokumentu OpenAPI interfejsu, po angielsku.
Trasy
- get/businessesList Businesses
- get/documents/{document_id}Get Document
- get/filesList Files
- post/filesSend File
- get/files/{file_id}Get File
- patch/files/{file_id}Assign File
- delete/files/{file_id}Delete File
- get/files/{file_id}/contentGet File Content
- get/files/{file_id}/documentGet File Document
- get/searchSearch
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.
Parametry
- Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403
urn:ocost:key:businessotherwise). 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.
get/public/v1/documents/{document_id}
Get Document
One document as ocost.document.v1.
Parametry
- document_idpathstring (uuid)wymaganeA document's
id: from a file'sdocumentsor 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:businessotherwise). 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.
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).
Parametry
- 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 | null
next_cursorof 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:businessotherwise). 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.
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.
Parametry
- Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403
urn:ocost:key:businessotherwise). 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.
Treść żądania · 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)wymaganeA 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
Odpowiedzi
- 200The same bytes, sent beforePublicFile
- 202Successful ResponsePublicFile
- 400Bad RequestProblem
- 401UnauthorizedProblem
- 403ForbiddenProblem
- 404Not FoundProblem
- 411Length RequiredProblem
- 413Content Too LargeProblem
- 415Unsupported Media TypeProblem
- 422Unprocessable ContentProblem
- 429Too Many RequestsProblem
- 503Service UnavailableProblem
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.
Parametry
- file_idpathstring (uuid)wymaganeThe file's
id, asPOST /filesanswered it - Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403
urn:ocost:key:businessotherwise). 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.
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.
Parametry
- file_idpathstring (uuid)wymaganeThe file's
id, asPOST /filesanswered it - Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403
urn:ocost:key:businessotherwise). 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.
Treść żądania · application/json
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.
Parametry
- file_idpathstring (uuid)wymaganeThe file's
id, asPOST /filesanswered it - Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403
urn:ocost:key:businessotherwise). 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.
get/public/v1/files/{file_id}/content
Get File Content
The original's bytes, as they were sent.
Parametry
- file_idpathstring (uuid)wymaganeThe file's
id, asPOST /filesanswered it - Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403
urn:ocost:key:businessotherwise). 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.
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.
Parametry
- file_idpathstring (uuid)wymaganeThe file's
id, asPOST /filesanswered it - Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403
urn:ocost:key:businessotherwise). 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.
get/public/v1/search
Search
Finds documents by what they say, in words and by meaning, best first: one result per document (a file without one as itself), each with its best passages and its card's facts that have the words, and links to the file and the document. Filters: the kind, the issue and due dates, a party by name or VAT ID, the gross, the direction, open or paid, an ECLASS category. match=exact finds only documents holding the text as written. Only the key's business's files outside the Trash. While the index is building, the words still answer (meaning: unavailable).
Parametry
- qquerystringwymaganeWhat to find: words, a number, or what it means
- kindqueryKind[] | nullOnly documents of these kinds; repeat it for several
- sincequerystring (date) | nullIssued on or after
- untilquerystring (date) | nullIssued on or before
- partyquerystring | nullA party's name, as read: seller, buyer…
- vat_idquerystring | nullA party's VAT ID, as read
- matchquery"exact" | "keywords" | "meaning" | "hybrid"exact: every document holding
qas written (case, accents and spacing aside), never one that only means the same; keywords: by its words; meaning: by what it means; hybrid: both - due_sincequerystring (date) | nullAn invoice due on or after
- due_untilquerystring (date) | nullAn invoice due on or before
- gross_minquerynumber | string | nullGross at least, in the business's currency
- gross_maxquerynumber | string | nullGross at most, in the business's currency
- directionquery"incoming" | "outgoing" | nullincoming: from suppliers; outgoing: to customers
- statusquery"open" | "paid" | nullAn invoice's: open (unpaid) or paid
- categoryquerystring | nullAn ECLASS code of any level: documents with a line in it or under it
- limitqueryintegerResults per page
- offsetqueryintegerResults to skip: the next page's start
- Ocost-BusinessheaderstringThe business this request acts in, by its id: one of your group's that the key reaches (403
urn:ocost:key:businessotherwise). 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.
Schematy
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 withsums: truefailedoutgoing: The business issued itpossible_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.
- x0numberwymaganeIts left edge, from the page's left
- x1numberwymaganeIts right edge, from the page's left
- y0numberwymaganeIts top edge, from the page's top
- y1numberwymaganeIts bottom edge, from the page's top
Candidate
A company of the group a file may belong to (needs_company).
- business_idstring (uuid)wymaganeWhat
PATCHnames - namestringwymagane
- whyCandidateWhywymagane
CandidateWhy
Why a company may be the one a file belongs to.
vat_id: Its VAT ID is on the documenttax_number: Its tax number is on the documentedrpou: Its ЄДРПОУ or РНОКПП is on the documentregister: Its register number and court are on the documentiban: Its account is the one the document asks to be paid intoname: Its name or address alone, which never decideshome: 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[]wymagane
- 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[]wymaganeThe paths it is about, as
sourcesnames them - nameCheckNamewymaganeWhat it checked;
sumssays whether it is one of the sums - passedbooleanwymagane
- sumsbooleanwymaganeOne 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 readvat: A VAT group's VAT is its net × rate (atthe rate)vat_net: The VAT groups' nets add up to the netvat_tax: The VAT groups' VAT adds up to the VATgross: Net plus VAT is the gross (the net, with no VAT printed)payable: What is left to pay is between nothing and the grosssigns: No total is negativededuction: A deducted invoice's net plus VAT is its gross (atwhich)deductions: The gross less the deductions is what is left to payquantity: A delivered quantity is positive, or the line is backordered (atthe line)skonto: A Skonto is plausible: up to 10 %, within a yearline: A line's quantity × price, less its discount, is its net (atthe 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 (atit)vat_lines: A VAT group's net is its lines' (atthe rate)line_tax: A line's printed VAT is its net × rate, and its net plus VAT its printed gross (atthe line)lines_tax: The lines' printed VAT adds up to their VAT group's (atthe rate)iban: The IBAN's check digits holdvat_id: A VAT ID has its country's formatidentifier: A party's identifier has its length and check digit (atits scheme: an ЄДРПОУ, a РНОКПП, a NIP)issued_on: The issue date is neither years ago nor aheaddue_on: The due date isn't before the issue dateservice: The service period starts before it endsvalid_until: A quote holds until after its issue datedelivery_on: The delivery date is near the issue datestated: The amounts stated in a second currency add upstated_rate: The amounts in both currencies agree at the rate printed, else the ECB's (atthe rate)payment_sum: A contract's payment: net plus VAT is its gross (atwhich)payment_vat: A contract's payment: its VAT is its net × ratepayment_sign: A contract's payment: its amounts are positivestep: A stepped rent's step falls in the term, in orderfirst_payment: A contract's first payment falls in its termdeposit: 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-invoiceread: Nothing speaks against itdoubt: A check failed (whynames 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'soutgoing: The business issued itunsure: Its parties don't say
"incoming" | "outgoing" | "unsure"
Document
ocost.document.v1: one document as Ocost read it.
- attentionAttention[]wymagane
- buyerParty | nullBG-7
- buyer_referencestring | nullBT-10
- cardCard | null
- checksCheck[]wymagane
- contract_referencestring | nullBT-12: the contract it refers to (an act's)
- currencystring | nullBT-5, ISO 4217
- deductionsDeduction[]wymagane
- deliver_toAddress | nullBG-15
- delivery_datestring (date) | nullBT-72
- directionDirectionwymagane
- due_datestring (date) | nullBT-9
- early_payment_discountsEarlyPaymentDiscount[]wymagane
- file_idstring (uuid)wymaganeThe file it is in
- idstring (uuid)wymaganeThe document
- invoicing_period_endstring (date) | nullBT-74
- invoicing_period_startstring (date) | nullBT-73
- issue_datestring (date) | nullBT-2
- kindKindwymagane
- kind_detailKindDetailwymagane
- linesLine[]wymagane
- numberstring | nullBT-1
- order_referencestring | nullBT-13
- order_referencesstring[]wymaganeEvery order it names
- other_partiesOtherParty[]wymaganeEvery other party named
- pagesinteger[]wymaganeIts pages in the file, from 1
- payeeParty | nullBG-10: when not the seller
- paymentPaymentwymagane
- 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_withReadWithwymagane
- schema"ocost.document.v1"Always this
- sellerParty | nullBG-4
- sourcesobjectwymaganePer 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
- totalsTotalswymagane
- 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[]wymagane
- worked_outWorkedOut[]wymagane
DocumentRef
One document a file holds.
- idstring (uuid)wymagane
- kindKindwymagane
- numberstring | nullBT-1, as printed
- pagesinteger[]wymaganeIts 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
- daysintegerwymagane
- due_datestring (date) | nullThe last day for it: the issue date plus
days - percentnumber (decimal)wymagane2 for 2 %
Fact
- amountnumber (decimal) | null
- currencystring | nullISO 4217, of
amount - datestring (date) | null
- kindFactKindwymagane
- labelstringwymaganeWhat 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 whatvalid_from: The day it is valid fromvalid_until: The day it is valid untilreference: A number naming something elseamount: An amountparty: Someone besides its issuer and recipientdate: Any other date: an inspection, an acceptanceother: Anything else
"deadline" | "valid_from" | "valid_until" | "reference" | "amount" | "party" | "date" | "other"
Factor
Who the receivable is assigned or sold to.
- namestringwymaganeAs the assignment note prints it
FieldError
One invalid field of a request.
- locstring | integer[]wymagane
- msgstringwymagane
- typestringwymagane
FileCompany
The business a file waiting for its company belongs to.
- business_idstring (uuid)wymaganeOne of the businesses the key reaches (
GET /businesses)
FileStatus
How far Ocost is with a file.
received: Stored, not read yetreading: Being readread: Read:documentslists what it holdsnot_read: Stored, not read;reasonsays whyfailed: Ocost couldn't read it;reasonsays whyneeds_company: Read, but its document names none of your group's companies or several:candidateslists them;PATCHit with thebusiness_idit belongs to, or someone answers in Ocost
"received" | "reading" | "read" | "not_read" | "failed" | "needs_company"
FoundBy
How a passage was found.
words: By its wordsmeaning: By its meaningboth: By both
"words" | "meaning" | "both"
FoundFact
- labelstringwymagane
- textstring | null
Hit
- found_byFoundBywymagane
- highlightsany[][]wymaganeWhere the words are in
text: [start, end) character ranges - pageintegerwymagane
- textstringwymagane
IdentifierScheme
What an identifier of a party is.
UA_EDRPOU: Ukraine: a legal entity's code ЄДРПОУ, 8 digitsUA_RNOKPP: Ukraine: a person's or sole trader's (ФОП) РНОКПП, 10 digitsUA_IPN: Ukraine: the VAT payer's number ІПН, 12 digitsEU_VAT: A VAT ID with its country prefix (alsovat_id)DE_STNR: Germany: a tax number, SteuernummerCOMMERCIAL_REGISTER: A register entry with its court (HRB 1234)PL_NIP: Poland: NIP, 10 digitsPL_REGON: Poland: REGON, 9 or 14 digitsPL_KRS: Poland: KRS number, 10 digitsGB_CRN: UK: Companies House number, 8 digits or 2 letters and 6FR_SIREN: France: SIREN, 9 digitsFR_SIRET: France: SIRET, 14 digitsCZ_ICO: Czechia: IČO, 8 digitsRO_CUI: Romania: CUI, 2 to 10 digitsNO_ORGNR: Norway: organisasjonsnummer, 9 digitsFI_YTUNNUS: Finland: Y-tunnus, 8 digits (without its dash)US_EIN: United States: EIN, 9 digitsUS_STATE_FILE: United States: a state's entity or file numberMD_IDNO: Moldova: IDNO, 13 digitsMD_IDNP: Moldova: a person's IDNP, 13 digitsMD_VAT: Moldova: cod TVA, 7 digitsOTHER: 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_codesays which)credit_note: A credit noteinvoice_correction: A corrected invoicereceipt: A receipt: paid alreadypro_forma: A pro forma invoice: not to paydelivery_note: A delivery noteorder: An order: a purchase, service, work or project orderorder_confirmation: An order's or a reservation's confirmationquote: A quote (offer)contract: A contract: agreements, leases, insurance policies, mandatesstatement: A factor's statementpayment_reminder: A payment remindertax_invoice: A tax invoice registered with the tax authority (a Ukrainian податкова накладна): VAT evidence, not to payother: Anything else:kind_detailandcardsay 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.
- idstringwymagane
- namestringwymagane
- numbersstring[]wymaganeIts numbers as Ocost keeps them
Line
BG-25.
- attributes{ [key]: string }wymaganeWhat it is, as printed: colour, size, material, brand, …
- backordered_quantitynumber (decimal) | nullStill to come
- base_quantitynumber (decimal) | nullBT-149: how many units
priceis 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
- idstringwymaganeBT-126: its position
- namestringwymaganeBT-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_code58)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 transfer59: SEPA direct debit48: 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
- rolePartyRolewymaganeWhat 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
- schemeIdentifierSchemewymagane
- validboolean | nullIts length and check digit hold; false: in doubt, a misread (never matched on); null: its scheme has no check
- valuestringwymaganeDigits 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 sellerbuyer: The buyerinvoicee: 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 buyerpayee: Who is paid, when not the sellership_to: Where the goods go (Warenempfänger)carrier: Who carries the goodsfactor: Who bought the receivabledebtor: Whose receivable it is (a factor's debtor)guarantor: Who guarantees it (Bürge)landlord: The landlordtenant: The tenantsubtenant: The subtenantcontractor: The contractorsubcontractor: The subcontractorprincipal: Who commissions the work (Auftraggeber, Bauherr)agent: Who acts for a party: a property manager, a brokerinsurer: The insurerpolicyholder: The policyholderother: Any other role:printed_rolesays 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;
ibanis 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
- statusintegerwymagane
- titlestringwymagane
- typestring
PublicBusiness
- idstring (uuid)wymaganeWhat
Ocost-Businessnames - namestringwymagane
- ownbooleanwymaganeThe business the key was made in
PublicBusinesses
- businessesPublicBusiness[]wymaganeThe 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)wymaganeThe 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_typestringwymagane
- created_atstring (date-time)wymagane
- documentsDocumentRef[]wymaganeOnce
read: what it holds - external_refstring | nullYour own id for it, as first sent
- external_refsstring[]wymaganeEvery id you sent with these bytes, the first first, each once; up to 50
- idstring (uuid)wymagane
- namestringwymagane
- 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_readorfailed - 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 - sha256stringwymaganeThe bytes' SHA-256, hex: the same bytes are one file; empty for a file Ocost made itself before it is hashed
- size_bytesintegerwymagane
- statusFileStatuswymagane
- updated_atstring (date-time)wymagane
PublicFiles
- filesPublicFile[]wymaganeOldest change first
- morebooleanwymaganeMore pages are there now: ask again at once
- next_cursorstring | nullAsk with this as
cursorfor 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, exactlyreader: From its pages
"e_invoice" | "reader"
Reason
Why a file is not_read or failed.
limit: The month's documents are used up; read onrenews_onmodel_off: This business may not have PDFs and images read; e-invoices still arenothing_found: No document in ittoo_large: Too many pages or too large an imagedamaged: Not a file Ocost can openunavailable: No reading service answered for a day; send it againfailed: Reading failedother: 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 numberedrpou: Its document names that company's ЄДРПОУ or РНОКППregister: Its document names that company's register number and courtiban: Its document asks to be paid into that company's accounthome: The key's own business: its document names no other of the groupperson: Chosen after Ocost asked, in Ocost or withPATCH
"header" | "vat_id" | "tax_number" | "edrpou" | "register" | "iban" | "home" | "person"
SearchMeaning
Whether search by meaning answered.
available: It didunavailable: 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[]wymaganeIts card's facts that have the words
- file_idstring (uuid)wymagane
- file_namestringwymagane
- file_urlstringwymaganeThe file, in this API
- grossnumber (decimal) | null
- issue_datestring (date) | null
- kindKind | null
- numberstring | null
- pagesinteger[]wymagane
- passagesHit[]wymaganeAt most 5, best first
- sellerstring | nullAs read
SearchResults
- meaningSearchMeaningwymagane
- resultsSearchResult[]wymagane
- totalintegerwymaganeHow many matched, up to the pool's 300
- truncatedbooleanwymaganeMore 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 (thenquoteis all there is) - confidenceConfidencewymagane
- 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 VATsmall: § 33 UStDV: a small amount, up to 250 €reverse_charge: § 13b, § 14a Abs. 5 UStG: the business owes the VATintra_eu: § 14a Abs. 3 UStG: an intra-community supplyexempt: § 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_stakebooleanwymaganeMissing, it costs the input VAT deduction
- itemTaxItemKindwymagane
- lawstringwymaganeThe paragraph that asks for it
TaxItemKind
What an invoice lacks, or has wrong, for its case.
supplier_name: The supplier's full namesupplier_address: The supplier's full addresssupplier_tax_id: The supplier's tax number or VAT IDrecipient_name: The recipient's full namerecipient_address: The recipient's full addressrecipient_not_us: It is addressed to someone else than the businessrecipient_address_not_ours: It is addressed to an address that isn't the business'sissued_on: The issue datenumber: The invoice numberdescription: The quantity and kind of the goods or servicesservice_date: The day of the supply or servicenet: The net per ratetax_rate: The VAT ratetax_amount: The VATexemption_note: The note on why it is exemptreverse_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 supplysupplier_vat_id: The supplier's VAT IDrecipient_vat_id: The recipient's VAT IDvat_charged: German VAT charged where the business owes it itself (§ 13b): not deductible, and paying it pays VAT twicevat_non_payer: Ukraine: ПДВ charged by a supplier Ukraine's register says is no VAT payer (платник ПДВ): no tax credit for itsupplier_idno: Moldova: the supplier's IDNOsupplier_vat_code: Moldova: the supplier's VAT code (cod TVA), where it charges VATvat_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_vatbooleanwymaganeIts 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 rateZ: Zero rated goodsE: Exempt from VATAE: Reverse charge: the buyer owes the VATK: Intra-community supply, VAT exemptG: Export outside the EU, free of VATO: Outside the scope of VATL: Canary Islands' IGICM: Ceuta and Melilla's IPSIB: 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)wymaganeBT-117
- taxable_amountnumber (decimal)wymaganeBT-116
WorkedOut
An amount Ocost worked out because the one read can't be it.
- fieldWorkedOutFieldwymaganeIts path in this document
- printednumber (decimal) | nullWhat was read
- ruleWorkedOutRulewymagane
WorkedOutField
The amount worked out, by its path.
totals.net: BT-109totals.tax: BT-110totals.gross: BT-112
"totals.net" | "totals.tax" | "totals.gross"
WorkedOutRule
How Ocost worked an amount out.
groups: The VAT groups' sumnet_tax: Net plus VATskonto: The gross read was the amount less Skontopayable: The gross read was what is left to payoutside: The net with an amount outside the VAT groups: a deposit, a tiptip: The gross read was the amount paid: the bill and its tip, read apart
"groups" | "net_tax" | "skonto" | "payable" | "outside" | "tip"
Zobacz też
- Szybki startPięć kroków do pierwszej faktury jako JSON: zarejestruj się, utwórz klucz, wyślij PDF, poczekaj, aż zostanie odczytany, odczytaj jego dokument. curl, Python i JavaScript.
- Klucze i uprawnieniaKlucze API: jak niesie je żądanie, ich wymiana, ich uprawnienia i odmowy.
- DokumentSchemat ocost.document.v1 w pojęciach EN 16931 (odwzorowywalny na UBL i CII): przykład, rodzaj i kierunek, źródła, kontrole, wersje oraz każde pole i każda wartość.
- Limity i błędyDokumenty planu na miesiąc, limity wywołań, rozmiary, błędy RFC 9457, ponawianie i miejsce przechowywania danych.