Skip to content

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

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 /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

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 /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

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