Reference: Integration
Interface for the leading system: the stream of events, the export state of an invoice and the lookup by DMS GUID. Instead of polling the events you can receive them as webhooks (see Webhooks).
| Method | Path | Summary |
|---|---|---|
| GET | /api/invoices/{id}/export |
Get the export state of an invoice |
| GET | /api/integration/events |
Fetch events |
| GET | /api/integration/invoices/by-dms-guid/{guid} |
Find an invoice by DMS GUID |
| POST | /api/integration/dms-transfers/next |
Fetch the next document for the document management system |
| POST | /api/integration/dms-transfers/{invoiceId} |
Report the stored document |
Get the export state of an invoice
Section titled “Get the export state of an invoice”GET /api/invoices/{id}/export
Operation id: getInvoiceExport
Returns the neutral export state of the invoice for the leading system: header, vendor, company, amounts as decimal strings, tax lines, payment terms, payment method, account coding, booking lines and document positions. The typical flow: learn about a change from listIntegrationEvents (or a webhook), then read the export of that invoice here.
revision and dataRevision tell what changed. revision changes with anything in the export. dataRevision changes only when data change that the receiver writes into its own invoice, so a pure status change leaves it alone. See the schema InvoiceExport for the details.
A key reads only invoices of its own company. An invoice of another company, an unknown id and an invoice in the trash answer 404.
Authentication: API key in the x-api-key header (ApiKey)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string (uuid) | yes | Id of the invoice. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The export state of the invoice. | InvoiceExport |
| 400 | The id is not a UUID. | 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.read. |
ApiError |
| 404 | The invoice does not exist, lies outside the company of the key or is in the trash (invoice.not_found). |
ApiError |
Fetch events
Section titled “Fetch events”GET /api/integration/events
Operation id: listIntegrationEvents
Returns the events about invoices in ascending order, starting after the number after. fineelik writes every change that matters to the outside as an event into one continuous stream; this route and the webhooks read the same stream.
Polling. Start with after=0 (or leave it out). Remember nextCursor of each answer and pass it as after in the next call. When hasMore is true, call again at once. By default 100 events are returned, at most 200.
Event types. invoice.received (accepted), invoice.status_changed (every change of status, with previousStatus), invoice.export_changed (data relevant for the export changed after review without a change of status, for example the account coding was corrected or the vendor changed) and invoice.processing_failed (see the schema IntegrationEvent). After an event, read the data with getInvoiceExport.
A key sees only the events of its own company.
Authentication: API key in the x-api-key header (ApiKey)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
after |
query | string | no | Return the events after this event number. Default 0, which means from the beginning. Use nextCursor of the previous answer. Default: "0". Pattern: ^\d{1,19}$. |
limit |
query | integer | no | Number of events per call, 1 to 200. Default 100. Default: 100. Minimum 1. Maximum 200. |
types |
query | string | no | Comma separated list of event types, for example invoice.status_changed,invoice.export_changed. Default: all types. |
companyId |
query | string (uuid) | no | Only events of this company (within your access). |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | One page of events. | IntegrationEvents |
| 400 | A parameter is invalid, for example an unknown event type. | 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.read. |
ApiError |
Find an invoice by DMS GUID
Section titled “Find an invoice by DMS GUID”GET /api/integration/invoices/by-dms-guid/{guid}
Operation id: findInvoiceByDmsGuid
Returns the invoice that belongs to a document of the document management system (invoiceId and status). The leading system uses it to find the invoice for an approval in its own workflow, so that it can call submitExternalDecision. An unknown GUID, an invoice of another company and an invoice in the trash all answer 404.
Authentication: API key in the x-api-key header (ApiKey)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
guid |
path | string | yes | GUID of the document in the document management system, as handed over in dmsGuid. GUID-shaped values are normalized to the ELO notation, so notation differences (braces, case) do not matter. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The invoice of this document. | InvoiceByDmsGuid |
| 401 | The API key is missing, invalid, expired or revoked. | ApiError |
| 403 | The owner of the API key does not hold the permission invoices.read. |
ApiError |
| 404 | No invoice for this GUID in the company of the key (invoice.not_found). |
ApiError |
Fetch the next document for the document management system
Section titled “Fetch the next document for the document management system”POST /api/integration/dms-transfers/next
Operation id: nextDmsTransfer
For companies with “Hand documents over to ELO”: returns the next document that arrived in fineelik itself (web app, mobile app, mailbox address, API) and has no DMS GUID yet, oldest first. Documents from the document management system, sample invoices and invoices in the trash are never returned, and only documents from the moment the setting was switched on count.
Every fetch is an attempt. The returned document is not offered again before its next attempt (5 minutes, 15 minutes, 1 hour, then every 6 hours), so the following documents keep moving if one fails. Fetch the file with getInvoicePdf, store it, then call reportDmsTransfer with the GUID or the reason.
A key sees only documents of its own company.
Authentication: API key in the x-api-key header (ApiKey)
Request body
Content type: application/json
Schema: DmsTransferNextRequest
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The next document, or item: null. |
DmsTransferNextResponse |
| 400 | The body is invalid, for example invoiceId is not a UUID. |
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. |
ApiError |
Report the stored document
Section titled “Report the stored document”POST /api/integration/dms-transfers/{invoiceId}
Operation id: reportDmsTransfer
Reports the GUID of the new document in the document management system (dmsGuid) or the reason why it was not stored (error). With a GUID, fineelik sets it on the invoice exactly once, notes it in the history and writes an invoice.export_changed event, so that the next sync writes the state of the invoice into the new document. Repeating the same GUID changes nothing (repeated).
With a reason, fineelik shows it on the invoice and offers the document again at its next attempt.
Authentication: API key in the x-api-key header (ApiKey)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
invoiceId |
path | string (uuid) | yes | Id of the invoice from nextDmsTransfer. |
Request body (required)
Content type: application/json
Schema: DmsTransferReportRequest
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The report was recorded. | DmsTransferReportResponse |
| 400 | The body is invalid: neither dmsGuid nor error, or both. |
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. |
ApiError |
| 404 | The invoice does not exist or lies outside the company of the key (invoice.not_found). |
ApiError |
| 409 | The GUID already belongs to another invoice (dms_transfer.guid_taken). |
ApiError |