Sign in

API reference

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

Ocost API 1 · The OpenAPI document

Routes

get/public/v1/documents/{document_id}

Get Document

One document as ocost.document.v1.

Parameters

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

Responses

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.

Parameters

  • 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

Responses

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

Request body · multipart/form-data

  • external_refstringYour own id for it (an Odoo bill's), kept and given back
  • filestring (binary)requiredA 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

Responses

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.

Parameters

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

Responses

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.

Parameters

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

Responses

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

Get File Content

The original's bytes, as they were sent.

Parameters

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

Responses

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.

Parameters

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

Responses

Schemas

Address

  • citystring | nullrequiredBT-37, BT-52
  • countrystring | nullrequiredBT-40, BT-55: ISO 3166-1 alpha-2
  • postal_codestring | nullrequiredBT-38, BT-53
  • streetstring | nullrequiredBT-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[]required
  • summarystring | nullrequired
  • titlestring | nullrequired

Check

  • atstring | nullrequiredThe rate or the line it is about
  • fieldsstring[]requiredThe paths it is about
  • namestringrequiredtotal, vat, vat_net, vat_tax, gross, payable, signs, skonto, deduction, deductions, quantity (the sums), dates, iban, vat_id, …
  • passedbooleanrequired
  • sumsbooleanrequiredOne 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 | nullrequiredBT-43, BT-58
  • phonestring | nullrequiredBT-42, BT-57

Deduction

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

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

Direction

"incoming" | "outgoing" | "unsure"

Document

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

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

DocumentRef

One document a file holds.

  • idstring (uuid)required
  • kindKindrequired
  • numberstring | nullrequiredBT-1, as printed
  • pagesinteger[]requiredIts pages in the file, from 1

EarlyPaymentDiscount

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

  • base_amountstring | nullrequiredWhat it is taken off, where printed; null: the amount due
  • daysintegerrequired
  • due_datestring (date) | nullrequiredThe last day for it: the issue date plus days
  • percentstringrequired2 for 2 %

Fact

  • amountstring | nullrequired
  • currencystring | nullrequired
  • datestring (date) | nullrequired
  • kindstringrequired
  • labelstringrequiredWhat it is, in the document's words
  • numberstring | nullrequired
  • pageinteger | nullrequired
  • textstring | nullrequired

FieldError

One invalid field of a request.

  • locstring | integer[]required
  • msgstringrequired
  • typestringrequired

FileStatus

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

FoundFact

  • labelstringrequired
  • textstring | nullrequired

Hit

  • found_by"words" | "meaning" | "both"required
  • highlightsany[][]requiredWhere the words are in text: [start, end) character ranges
  • pageintegerrequired
  • textstringrequired

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 }requiredWhat it is, as printed: colour, size, material, brand, …
  • backordered_quantitystring | nullrequiredStill to come
  • base_quantitystring | nullrequiredBT-149: how many units price is for; null: one
  • batchstring | nullrequired
  • discount_percentstring | nullrequiredThe line's discount: 5
  • idstringrequiredBT-126: its position
  • namestringrequiredBT-153
  • net_amountstring | nullrequiredBT-131
  • ordered_quantitystring | nullrequiredA delivery note's
  • pricestring | nullrequiredBT-146: the net price
  • pznstring | nullrequiredA medicine's PZN
  • quantitystring | nullrequiredBT-129
  • seller_item_idstring | nullrequiredBT-155: the article number
  • standard_item_idstring | nullrequiredBT-157: the GTIN (scheme 0160)
  • unitstring | nullrequiredBT-130: UNECE Rec 20 (C62, HUR, KGM) or Rec 21 (XCT); null when none is printed
  • vat_categorystring | nullrequiredBT-151
  • vat_ratestring | nullrequiredBT-152, percent

OtherParty

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

Party

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

Payment

BG-16.

  • bicstring | nullrequiredBT-86
  • ibanstring | nullrequiredBT-84
  • means"transfer" | "direct_debit" | "card" | "already_paid" | nullrequiredThe same, as a word
  • means_codestring | nullrequiredBT-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 | nullrequiredThe days the terms give to pay in full from the issue date
  • paid_onstring (date) | nullrequiredThe day it says it was paid or charged, where printed
  • termsstring | nullrequiredBT-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
  • statusintegerrequired
  • titlestringrequired
  • typestring

PublicFile

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

  • content_typestringrequired
  • created_atstring (date-time)required
  • documentsDocumentRef[]requiredOnce read: what it holds
  • external_refstring | nullrequiredYour own id for it, as sent
  • idstring (uuid)required
  • namestringrequired
  • pagesinteger | nullrequiredIts pages, once counted
  • pages_readinteger | nullrequiredThe first pages read of a file longer than Ocost reads; null: all of them
  • reasonReason | nullrequiredWhy it is not_read or failed
  • renews_onstring (date) | nullrequiredFor reason: limit: the day the month's documents renew; it is read then by itself
  • sha256stringrequiredThe bytes' SHA-256, hex: the same bytes are one file
  • size_bytesintegerrequired
  • statusFileStatusrequired
  • updated_atstring (date-time)required

PublicFiles

  • filesPublicFile[]requiredOldest change first
  • morebooleanrequiredMore pages are there now: ask again at once
  • next_cursorstring | nullrequiredAsk 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 | nullrequiredAs read
  • currencystring | nullrequired
  • document_idstring (uuid) | nullrequiredNull for a file without one
  • document_urlstring | nullrequiredThe document, in this API
  • factsFoundFact[]requiredIts card's facts that have the words
  • file_idstring (uuid)required
  • file_namestringrequired
  • file_urlstringrequiredThe file, in this API
  • grossstring | nullrequired
  • issue_datestring (date) | nullrequired
  • kindKind | nullrequired
  • numberstring | nullrequired
  • pagesinteger[]required
  • passagesHit[]requiredAt most 5, best first
  • sellerstring | nullrequiredAs read

SearchResults

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

Source

  • confidenceConfidencerequired
  • pageinteger | nullrequiredWhere it was read, from 1
  • quotestring | nullrequiredThe words it was read from
  • whystring | nullrequiredFor a doubt: the check that failed

TaxCheck

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

  • casestringrequiredstandard, small, reverse_charge, intra_eu, exempt
  • missingTaxItem[]required

TaxItem

  • at_stakebooleanrequiredMissing, it costs the input VAT deduction
  • itemstringrequired
  • lawstringrequiredThe paragraph that asks for it

Totals

BG-22.

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

VatGroup

BG-23.

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

WorkedOut

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

  • fieldstringrequiredIts path in this document
  • printedstring | nullrequiredWhat was read
  • rulestringrequired