Anmelden

API-Referenz

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

Ocost API 1 · Das OpenAPI-Dokument

Die Beschreibungen der Referenz kommen aus dem OpenAPI-Dokument der API und sind englisch.

Routen

get/public/v1/documents/{document_id}

Get Document

One document as ocost.document.v1.

Parameter

  • document_idpathstring (uuid)PflichtA document's id: from a file's documents or a search result

Antworten

get/public/v1/files

List Files

The files changed at or after updated_since, oldest change first, of the statuses asked for: 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.

Parameter

  • statusqueryFileStatus[] | nullOnly files of these statuses; repeat it for several
  • updated_sincequerystring (date-time) | nullFiles changed at or after this time (ISO 8601)
  • cursorquerystring | nullnext_cursor of the page before
  • limitqueryintegerFiles per page

Antworten

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; the first external_ref stays). 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).

Anfrage · multipart/form-data

  • external_refstringYour own id for it (an Odoo bill's), kept and given back
  • filestring (binary)PflichtA PDF, an image (JPEG, PNG, TIFF, WebP) or an e-invoice's XML (XRechnung, UBL, CII); at most 25 MB
  • namestringIts file name; the upload's own when left out

Antworten

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.

Parameter

  • file_idpathstring (uuid)PflichtThe file's id, as POST /files answered it

Antworten

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.

Parameter

  • file_idpathstring (uuid)PflichtThe file's id, as POST /files answered it

Antworten

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

Get File Content

The original's bytes, as they were sent.

Parameter

  • file_idpathstring (uuid)PflichtThe file's id, as POST /files answered it

Antworten

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.

Parameter

  • file_idpathstring (uuid)PflichtThe file's id, as POST /files answered it

Antworten

Schemata

Address

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

Attention

What a person should look at before booking it.

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

Card

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

  • factsFact[]Pflicht
  • summarystring | nullPflicht
  • titlestring | nullPflicht

Check

  • atstring | nullPflichtThe rate or the line it is about
  • fieldsstring[]PflichtThe paths it is about
  • namestringPflichttotal, vat, vat_net, vat_tax, gross, payable, signs, skonto, deduction, deductions, quantity (the sums), dates, iban, vat_id, …
  • passedbooleanPflicht
  • sumsbooleanPflichtOne of the sums: fill a bill only when all pass

Confidence

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

"checked" | "read" | "doubt"

Contact

  • emailstring | nullPflichtBT-43, BT-58
  • phonestring | nullPflichtBT-42, BT-57

Deduction

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

  • grossstring | nullPflicht
  • issue_datestring (date) | nullPflicht
  • netstring | nullPflicht
  • numberstring | nullPflicht
  • taxstring | nullPflicht

Direction

"incoming" | "outgoing" | "unsure"

Document

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

  • attentionAttention[]Pflicht
  • buyerParty | nullPflichtBG-7
  • buyer_referencestring | nullPflichtBT-10
  • cardCard | nullPflicht
  • checksCheck[]Pflicht
  • currencystring | nullPflichtBT-5, ISO 4217
  • deductionsDeduction[]Pflicht
  • deliver_toAddress | nullPflichtBG-15
  • delivery_datestring (date) | nullPflichtBT-72
  • directionDirectionPflichtincoming: to the business; outgoing: it issued it; unsure
  • due_datestring (date) | nullPflichtBT-9
  • early_payment_discountsEarlyPaymentDiscount[]Pflicht
  • file_idstring (uuid)Pflicht
  • idstring (uuid)Pflicht
  • invoicing_period_endstring (date) | nullPflichtBT-74
  • invoicing_period_startstring (date) | nullPflichtBT-73
  • issue_datestring (date) | nullPflichtBT-2
  • kindKindPflicht
  • kind_detailstringPflichtThe exact kind, for information
  • linesLine[]Pflicht
  • numberstring | nullPflichtBT-1
  • order_referencestring | nullPflichtBT-13
  • order_referencesstring[]PflichtEvery order it names
  • other_partiesOtherParty[]Pflicht
  • pagesinteger[]PflichtIts pages in the file, from 1
  • payeeParty | nullPflichtBG-10: when not the seller
  • paymentPaymentPflicht
  • possible_duplicate_ofstring (uuid) | nullPflichtAn earlier document of the same kind, number and seller
  • preceding_invoicestring | nullPflichtBT-25
  • read_with"e_invoice" | "reader"Pflicht
  • schema"ocost.document.v1"
  • sellerParty | nullPflichtBG-4
  • sources{ [key]: Source }PflichtPer value, by its path (number, totals.gross, seller.vat_id)
  • tax_checkTaxCheck | nullPflicht
  • totalsTotalsPflicht
  • type_codestring | nullPflichtBT-3, UNCL 1001: 380, 381, 384, 326
  • valid_untilstring (date) | nullPflichtA quote's
  • vat_breakdownVatGroup[]Pflicht
  • worked_outWorkedOut[]Pflicht

DocumentRef

One document a file holds.

  • idstring (uuid)Pflicht
  • kindKindPflicht
  • numberstring | nullPflichtBT-1, as printed
  • pagesinteger[]PflichtIts pages in the file, from 1

EarlyPaymentDiscount

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

  • base_amountstring | nullPflichtWhat it is taken off, where printed; null: the amount due
  • daysintegerPflicht
  • due_datestring (date) | nullPflichtThe last day for it: the issue date plus days
  • percentstringPflicht2 for 2 %

Fact

  • amountstring | nullPflicht
  • currencystring | nullPflicht
  • datestring (date) | nullPflicht
  • kindstringPflicht
  • labelstringPflichtWhat it is, in the document's words
  • numberstring | nullPflicht
  • pageinteger | nullPflicht
  • textstring | nullPflicht

FieldError

One invalid field of a request.

  • locstring | integer[]Pflicht
  • msgstringPflicht
  • typestringPflicht

FileStatus

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

FoundFact

  • labelstringPflicht
  • textstring | nullPflicht

Hit

  • found_by"words" | "meaning" | "both"Pflicht
  • highlightsany[][]PflichtWhere the words are in text: [start, end) character ranges
  • pageintegerPflicht
  • textstringPflicht

Kind

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

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

Line

BG-25.

  • attributes{ [key]: string }PflichtWhat it is, as printed: colour, size, material, brand, …
  • backordered_quantitystring | nullPflichtStill to come
  • base_quantitystring | nullPflichtBT-149: how many units price is for; null: one
  • batchstring | nullPflicht
  • discount_percentstring | nullPflichtThe line's discount: 5
  • idstringPflichtBT-126: its position
  • namestringPflichtBT-153
  • net_amountstring | nullPflichtBT-131
  • ordered_quantitystring | nullPflichtA delivery note's
  • pricestring | nullPflichtBT-146: the net price
  • pznstring | nullPflichtA medicine's PZN
  • quantitystring | nullPflichtBT-129
  • seller_item_idstring | nullPflichtBT-155: the article number
  • standard_item_idstring | nullPflichtBT-157: the GTIN (scheme 0160)
  • unitstring | nullPflichtBT-130: UNECE Rec 20 (C62, HUR, KGM) or Rec 21 (XCT); null when none is printed
  • vat_categorystring | nullPflichtBT-151
  • vat_ratestring | nullPflichtBT-152, percent

OtherParty

  • addressAddress | nullPflichtBG-5, BG-8
  • contactContact | nullPflichtBG-6, BG-9
  • legal_registration_idstring | nullPflichtBT-30, BT-47: the register entry (HRB …)
  • namestring | nullPflichtBT-27 (seller), BT-44 (buyer)
  • printed_rolestring | nullPflichtThe words printed for its role
  • rolestringPflichtWhat it is to the document: invoicee, payee, ship_to, carrier, factor, landlord, tenant, …
  • tax_registration_idstring | nullPflichtBT-32: the tax number (Steuernummer)
  • vat_idstring | nullPflichtBT-31, BT-48
  • websitestring | nullPflicht

Party

  • addressAddress | nullPflichtBG-5, BG-8
  • contactContact | nullPflichtBG-6, BG-9
  • legal_registration_idstring | nullPflichtBT-30, BT-47: the register entry (HRB …)
  • namestring | nullPflichtBT-27 (seller), BT-44 (buyer)
  • tax_registration_idstring | nullPflichtBT-32: the tax number (Steuernummer)
  • vat_idstring | nullPflichtBT-31, BT-48
  • websitestring | nullPflicht

Payment

BG-16.

  • bicstring | nullPflichtBT-86
  • ibanstring | nullPflichtBT-84
  • means"transfer" | "direct_debit" | "card" | "already_paid" | nullPflichtThe same, as a word
  • means_codestring | nullPflichtBT-81, UNCL 4461: 58 SEPA credit transfer, 59 SEPA direct debit, 48 card; null when it doesn't say or it was paid already
  • net_daysinteger | nullPflichtThe days the terms give to pay in full from the issue date
  • paid_onstring (date) | nullPflichtThe day it says it was paid or charged, where printed
  • termsstring | nullPflichtBT-20, as printed

Problem

RFC 9457 problem details, with errors for invalid fields.

  • detailstring | null
  • errorsFieldError[] | null
  • instancestring | null
  • reasonstring | nullRead-only (type urn:ocost:read-only, docs/specs/056): why, trial_ended, unpaid or ended
  • renews_onstring (date) | nullA month's limit used (type urn:ocost:limit:<kind>): the day it renews
  • statusintegerPflicht
  • titlestringPflicht
  • typestring

PublicFile

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

  • content_typestringPflicht
  • created_atstring (date-time)Pflicht
  • documentsDocumentRef[]PflichtOnce read: what it holds
  • external_refstring | nullPflichtYour own id for it, as sent
  • idstring (uuid)Pflicht
  • namestringPflicht
  • pagesinteger | nullPflichtIts pages, once counted
  • pages_readinteger | nullPflichtThe first pages read of a file longer than Ocost reads; null: all of them
  • reasonReason | nullPflichtWhy it is not_read or failed
  • renews_onstring (date) | nullPflichtFor reason: limit: the day the month's documents renew; it is read then by itself
  • sha256stringPflichtThe bytes' SHA-256, hex: the same bytes are one file
  • size_bytesintegerPflicht
  • statusFileStatusPflicht
  • updated_atstring (date-time)Pflicht

PublicFiles

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

Reason

Why a file is not_read or failed.

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

SearchResult

  • buyerstring | nullPflichtAs read
  • currencystring | nullPflicht
  • document_idstring (uuid) | nullPflichtNull for a file without one
  • document_urlstring | nullPflichtThe document, in this API
  • factsFoundFact[]PflichtIts card's facts that have the words
  • file_idstring (uuid)Pflicht
  • file_namestringPflicht
  • file_urlstringPflichtThe file, in this API
  • grossstring | nullPflicht
  • issue_datestring (date) | nullPflicht
  • kindKind | nullPflicht
  • numberstring | nullPflicht
  • pagesinteger[]Pflicht
  • passagesHit[]PflichtAt most 5, best first
  • sellerstring | nullPflichtAs read

SearchResults

  • meaning"available" | "unavailable"Pflichtunavailable: the index is building or its model unreachable; the words still answer
  • resultsSearchResult[]Pflicht
  • totalintegerPflichtHow many matched, up to the pool's 300
  • truncatedbooleanPflichtMore matched than the pool holds

Source

  • confidenceConfidencePflicht
  • pageinteger | nullPflichtWhere it was read, from 1
  • quotestring | nullPflichtThe words it was read from
  • whystring | nullPflichtFor a doubt: the check that failed

TaxCheck

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

  • casestringPflichtstandard, small, reverse_charge, intra_eu, exempt
  • missingTaxItem[]Pflicht

TaxItem

  • at_stakebooleanPflichtMissing, it costs the input VAT deduction
  • itemstringPflicht
  • lawstringPflichtThe paragraph that asks for it

Totals

BG-22.

  • grossstring | nullPflichtBT-112
  • netstring | nullPflichtBT-109
  • payablestring | nullPflichtBT-115: what is left to pay; null when it is the gross
  • prices_include_vatbooleanPflichtIts lines' prices and amounts include VAT (a receipt)
  • taxstring | nullPflichtBT-110

VatGroup

BG-23.

  • categorystring | nullPflichtBT-118, UNCL 5305: S, Z, E, AE, K, G, O
  • exemption_reasonstring | nullPflichtBT-120
  • ratestring | nullPflichtBT-119, percent: 19
  • tax_amountstringPflichtBT-117
  • taxable_amountstringPflichtBT-116

WorkedOut

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

  • fieldstringPflichtIts path in this document
  • printedstring | nullPflichtWhat was read
  • rulestringPflicht