Uploading invoices
Deliver an invoice
Section titled “Deliver an invoice”POST /api/invoices/upload takes a multipart form with the field file. Exactly one file per call, a PDF (or an e-invoice as XML): fineelik always receives one invoice per file, so containers have to be split before. The size limit is 20 MB.
The optional field companyId (the UUID of a company) is meant for signed-in people. A key always delivers into its own company (without a binding: the default company). A different companyId is answered with 404.
curl -X POST https://<your-instance>/api/invoices/upload \ -H "x-api-key: <your-key>" \ -F "file=@invoice.pdf;type=application/pdf"Answers:
| Status | Meaning |
|---|---|
| 201 | created. The body contains invoiceId and status. |
| 200 | the same file (SHA-256) already exists in this company. The body names the existing invoice. |
| 400 | no file, not a PDF or e-invoice, or an invalid companyId |
| 413 | the file is larger than 20 MB |
| 401 | key missing, expired or revoked |
| 403 | the key may not use this company |
| 429 | too many uploads, see Errors and limits |
Safe to repeat
Section titled “Safe to repeat”Delivery is idempotent by content. After a network error a job may send the same file again. Whether an exact duplicate is rejected or accepted is a setting of your instance; the default is to reject it with 200 and a reference to the existing invoice. Idempotency applies per company: the same file in another company is created there.
Hand over a document from ELO
Section titled “Hand over a document from ELO”POST /api/ingest/handover needs the right invoices.upload and the additional field dmsGuid. It is additionally idempotent by the GUID of the document: the same GUID in the same company gives 200 with the existing invoice.
The GUID is unique across the instance. If it already belongs to another company (for example the same document sent with the key of another client), fineelik answers 409 with the code ingest.dms_guid_other_company and says nothing about the other invoice.
To find the invoice for a document later, use GET /api/integration/invoices/by-dms-guid/{guid}. It returns invoiceId and status, and 404 outside the key’s company.
What happens next
Section titled “What happens next”Processing runs asynchronously: text recognition, reading, matching (vendor, duplicates, template) and then either review by accounting or, depending on the settings, approval. Read the state whenever you like.
Read the state
Section titled “Read the state”GET /api/invoices/{id} returns the invoice with its status, header and line data, accounting and the company.
| Status | Meaning |
|---|---|
captured |
received, processing has started |
extracted |
read from the document |
review_required |
waits for review by accounting |
enriched |
coded and checked. With approval outside fineelik the invoice waits here for your report, see statusReason |
approval_pending |
waits for approval inside fineelik |
approved |
approved |
rejected |
rejected |
payment_pending, payment_approved |
in the payment process |
paid |
paid |
cancelled, archived, written_off, duplicate |
ended |
not_an_invoice, preflight_rejected |
not processed as an invoice |
GET /api/invoices lists with filters (status, search, companyId, dates, amounts and more) and pages with page (from 1) and pageSize (default 25, at most 500). It answers items, total, page and pageSize. See Reference: invoices for all parameters.
Read the document, the history and the approval proof
Section titled “Read the document, the history and the approval proof”| Call | Returns |
|---|---|
GET /api/invoices/{id}/pdf |
the document of the invoice |
GET /api/invoices/{id}/audit |
the history: who did what and when |
GET /api/invoices/{id}/approval-record?format=pdf |
the approval proof as PDF (format=csv for CSV) |
All three need the right invoices.read and, with an API key, stay within the key’s company. Details are in Reference: invoices.
If a customer works with approval outside fineelik, continue with External approval.