Skip to content

Reference: Ingest

Hand invoices to fineelik: a plain upload or the hand over from a document management system such as ELO.

Method Path Summary
POST /api/invoices/upload Upload an invoice
POST /api/ingest/handover Hand over an invoice from a document management system

POST /api/invoices/upload

Operation id: uploadInvoice

Hands one invoice to fineelik. Send a multipart form with the field file: exactly one PDF per call (containers must be split before). Processing then runs asynchronously: read the state with getInvoice or follow the events.

Idempotent by content. The same file (SHA-256) in the same company answers 200 with duplicate: true and the existing invoice, instead of creating a second one. A job may therefore send the same file again after a network error. By default the instance refuses such a repeat this way (an instance can be configured to accept repeats as new invoices). The same file in another company is created there as new. Id and status of an invoice from a foreign company never appear in an answer.

Company. A key always uploads into its own company (without binding: the default company). The field companyId is meant for signed-in users. With a key, a different companyId answers 404.

Rate limit: by default at most 60 uploads per minute per key, then 429 with Retry-After.

Authentication: API key in the x-api-key header (ApiKey)

Request body (required)

Content type: multipart/form-data

Field Type Required Description
file string (binary) yes The invoice as a PDF file. Exactly one file per call.
companyId string (uuid) no Company to upload into. Meant for signed-in users. An API key always uploads into its own company (without binding: the default company); a different value answers 404.

Responses

Status Meaning Body
200 The same file was already known in this company (duplicate is true). Nothing new was created; the body names the existing invoice. UploadResponse
201 The invoice was created and processing started. UploadResponse
400 No file (upload.no_file), not a PDF (upload.not_pdf) or an invalid companyId. ApiError
401 The API key is missing, invalid, expired or revoked. ApiError
403 The owner of the API key does not hold the permission invoices.upload. Also 403 api_key.no_company when the key is bound to no company that its owner may see. ApiError
404 The companyId differs from the company of the key (company.not_found). ApiError
413 The file is larger than the limit of 20 MB. ApiError
429 Rate limit reached. Wait the number of seconds given in Retry-After. Header: Retry-After. ApiError

Hand over an invoice from a document management system

Section titled “Hand over an invoice from a document management system”

POST /api/ingest/handover

Operation id: handoverInvoice

For the ELO integration component. The component reads a document from the document management system (DMS, for example ELO) and pushes it to fineelik. fineelik needs no access to the DMS for this. Send a multipart form with the PDF in the field file and the text fields below, dmsGuid being required.

Idempotent by dmsGuid. The same GUID in the same company answers 200 with duplicate: true and the existing invoice. The GUID is unique across the instance. When it already belongs to a different company (for example the same document sent with the key of another client), the answer is 409 ingest.dms_guid_other_company, without any information about the other invoice. As with uploadInvoice, the same file content in the same company is a duplicate too.

Company. A key always hands over into its own company (without binding: the default company). There is no companyId field.

The invoice is processed asynchronously like an upload.

Authentication: API key in the x-api-key header (ApiKey)

Request body (required)

Content type: multipart/form-data

Field Type Required Description
file string (binary) yes The invoice as a PDF file. Exactly one file per call.
dmsGuid string yes GUID of the document in the document management system. This is the anchor for idempotency and unique across the instance. GUID-shaped values are normalized to the ELO notation (XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX), so notation differences (braces, case) do not matter.
containerGuid string no GUID of the folder in container mode. Kept only as a note in the history.
mask string no Mask (document type) of the source document. Kept only as a note in the history.
sourcePath string no Path of the source document. Kept only as a note in the history.

Responses

Status Meaning Body
200 The document (dmsGuid) or the same file was already known in this company (duplicate is true). Nothing new was created; the body names the existing invoice. UploadResponse
201 The invoice was created and processing started. UploadResponse
400 No file (upload.no_file), not a PDF (upload.not_pdf) or dmsGuid is missing. ApiError
401 The API key is missing, invalid, expired or revoked. ApiError
403 The owner of the API key does not hold the permission invoices.upload. Also 403 api_key.no_company when the key is bound to no company that its owner may see. ApiError
409 The dmsGuid already belongs to a different company (ingest.dms_guid_other_company). ApiError
413 The file is larger than the limit of 20 MB. ApiError