Reference: Invoices
Read invoices and their state, document, history and approval record, and report an approval that ran outside fineelik.
| Method | Path | Summary |
|---|---|---|
| GET | /api/invoices |
List invoices |
| GET | /api/invoices/{id} |
Get an invoice |
| GET | /api/invoices/{id}/pdf |
Download the document of an invoice |
| GET | /api/invoices/{id}/audit |
Get the history of an invoice |
| GET | /api/invoices/{id}/approval-record |
Download the approval record of an invoice |
| POST | /api/invoices/{id}/external-decision |
Report an approval decision from outside |
List invoices
Section titled “List invoices”GET /api/invoices
Operation id: listInvoices
Lists invoices with filters, sorting and paging (page, pageSize, up to 500 per page). A key sees only the invoices of its own company.
To find the invoices that wait for an approval from outside, filter with status=enriched and look at the field statusReason (approval_external).
Authentication: API key in the x-api-key header (ApiKey)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
status |
query | string | no | Only invoices with this status. One of: captured, preflight_rejected, not_an_invoice, extracted, review_required, enriched, approval_pending, approved, rejected, payment_pending, payment_approved, paid, archived, duplicate, written_off, cancelled, deleted. |
search |
query | string | no | Search text, 1 to 200 characters. Up to 200 characters. |
companyId |
query | string (uuid) | no | Only invoices of this company (within your access). |
view |
query | string | no | A predefined group of statuses, as in the tabs of the invoice list in the web app. all leaves out the trash. trash is reserved for signed-in users who may delete invoices; an API key gets 403 invoice.trash_forbidden. One of: all, review, approval, ready, run, issues, processing, trash. |
vendorId |
query | string (uuid) | no | Only invoices of this vendor. |
vendorIds |
query | string | no | Several vendor ids separated by commas (1 to 50), for the same vendor in several companies. Together with vendorId it means “one of these”. |
dueFrom |
query | string (date) | no | Earliest due date, inclusive (YYYY-MM-DD). |
dueTo |
query | string (date) | no | Latest due date, inclusive (YYYY-MM-DD). |
discount |
query | string | no | open: only invoices with a cash discount whose period still runs. One of: open. |
currency |
query | string | no | Only invoices in this currency (ISO 4217, for example EUR). Pattern: ^[A-Z]{3}$. |
dateFrom |
query | string (date) | no | Earliest invoice date, inclusive (YYYY-MM-DD). |
dateTo |
query | string (date) | no | Latest invoice date, inclusive (YYYY-MM-DD). |
amountMin |
query | string | no | Smallest gross amount, inclusive, as a decimal string. Pattern: ^-?\d+(\.\d+)?$. |
amountMax |
query | string | no | Largest gross amount, inclusive, as a decimal string. Pattern: ^-?\d+(\.\d+)?$. |
sort |
query | string | no | Column to sort by. Empty values (no date, no amount) come last. Default createdAt. One of: createdAt, invoiceDate, dueDate, grossTotal, netTotal, vendorName, invoiceNumber, status. Default: "createdAt". |
direction |
query | string | no | Sort direction. Default desc, so the newest come first. One of: asc, desc. Default: "desc". |
page |
query | integer | no | Page number, starting at 1. Default 1. Default: 1. Minimum 1. Maximum 9007199254740991. |
pageSize |
query | integer | no | Invoices per page, 1 to 500. Default 25. Default: 25. Minimum 1. Maximum 500. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | One page of the list. | InvoiceList |
| 400 | A parameter is invalid. | 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. Also 403 invoice.trash_forbidden for view=trash. |
ApiError |
Get an invoice
Section titled “Get an invoice”GET /api/invoices/{id}
Operation id: getInvoice
Returns the invoice with its status, header and line data, account coding, approval and payment state, references (duplicate, reversal) and its company. A key sees only invoices of its own company. An invoice of another company, an unknown id 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 |
|---|---|---|---|---|
id |
path | string (uuid) | yes | Id of the invoice. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The invoice. | InvoiceDetail |
| 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 |
Download the document of an invoice
Section titled “Download the document of an invoice”GET /api/invoices/{id}/pdf
Operation id: getInvoiceDocument
Returns the document as it was received. This is normally a PDF. An e-invoice that came in as an XML file is returned as an attachment with the type application/xml. An invoice created from an expense receipt can have an image as its document.
Every download is recorded in the audit log together with the API key.
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 document, as a file. | |
| 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 or its document does not exist (invoice.original_not_found), lies outside the company of the key or is in the trash (invoice.not_found). Invoices without a document, such as imported open items, have none to download. |
ApiError |
Get the history of an invoice
Section titled “Get the history of an invoice”GET /api/invoices/{id}/audit
Operation id: listInvoiceHistory
Returns the history (audit trail) of the invoice, newest first, limited to the latest 200 entries. The entries about the approval tasks of the invoice belong to it. Each entry names the action, who acted (a user, or an API key in actorApiKeyId) and the state before and after.
An approval reported from outside (submitExternalDecision) appears as invoice.status_changed, with decidedBy, comment and externalRef in metadata and the API key as the actor.
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 history entries. | InvoiceHistory |
| 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 |
Download the approval record of an invoice
Section titled “Download the approval record of an invoice”GET /api/invoices/{id}/approval-record
Operation id: downloadApprovalRecord
Returns the approval record (“Freigabenachweis”) as a file download: the header of the invoice, the approval chain with all intermediate steps, queries and the history. It is meant to be passed on to a bank, tax advisor or auditor. An approval reported from outside shows the decider, the reason and the reference.
The language of the file is the language of the account that owns the key.
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. |
format |
query | string | no | File format. Default pdf. One of: pdf, csv. Default: "pdf". |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The approval record as an attachment. | |
| 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. | ApiError |
Report an approval decision from outside
Section titled “Report an approval decision from outside”POST /api/invoices/{id}/external-decision
Operation id: submitExternalDecision
Reports the decision of an approval that ran outside fineelik, for example in an ELO workflow.
When it applies. For each company the settings say whether invoices are approved “in fineelik” or “outside”. Without a licence for the approvals module every company counts as “outside” and the setting is locked. With “outside”, fineelik creates no approval task after the review. The invoice stays in the status enriched (“Kontiert”) with statusReason approval_external until the leading system reports the decision here. approved sets the invoice to approved, rejected sets it to rejected. Open items and the payment run then continue as usual. listInvoices with status=enriched shows which invoices wait. Invoices that were already coded before a company was switched to “outside” (enriched with another reason or none) can be reported too. Invoices in a running internal approval (approval_pending) cannot.
Idempotent. A job may send the same decision again after a network error: the answer is 200 with applied: false, even if the company was switched to “in fineelik” in the meantime. A contradicting decision for an invoice that was already reported is not applied (409 approval.external_conflict). When two reports arrive at the same time, the first wins and the second gets the answer for the state that then holds.
History. The report appears in the history of the invoice (invoice.status_changed with decidedBy, comment, externalRef and the key as the actor) and in the approval record with decider, reason and reference.
After the report. After a rejection (rejected, reason approval_external_rejected), accounting can bring the invoice back into review in fineelik and close it again. It then waits for a decision once more, and the leading system restarts it after its own clarification. After an approval (approved with reason approval_external_approved, and in the payment states payment_pending and payment_approved as long as this approval is the latest), fineelik locks reopening (409 invoice.reopen_locked_external): corrections have to be made in the leading system.
A key reports only for invoices of its own company.
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. |
Request body (required)
Content type: application/json
Schema: ExternalDecisionRequest
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The decision was applied (applied is true) or was already on record (applied is false). |
ExternalDecisionResponse |
| 400 | The body is invalid: decision is missing or unknown, a field is too long or an unknown field was sent. |
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.decide_external. |
ApiError |
| 404 | The invoice does not exist, lies outside the access, or is not in the company the key is bound to (invoice.not_found). |
ApiError |
| 409 | Conflict. Look at code: approval.external_not_enabled (the approval of this company runs in fineelik), approval.external_wrong_status (the invoice does not wait for a report; params.status names its status) or approval.external_conflict (it was decided differently already). |
ApiError |