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 |
Upload an invoice
Section titled “Upload an invoice”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 |