External approval
In every company you choose in the settings where invoices are approved: in fineelik or in an external system such as an ELO workflow. Without the approvals module, approval always runs outside fineelik and the setting is locked.
With approval outside fineelik, fineelik creates no approval task after review. The invoice stays in status enriched (“coded”) with the statusReason approval_external until the leading system reports the decision with POST /api/invoices/{id}/external-decision. After that, open items and payment runs work as usual.
To see which invoices are waiting, call GET /api/invoices?status=enriched and look at statusReason. Invoices that were coded before the company was switched to external approval (enriched with another or no reason) can be reported as well. Invoices in a running internal approval (approval_pending) cannot.
Request
Section titled “Request”The body is JSON:
| Field | Required | Meaning |
|---|---|---|
decision |
yes | approved or rejected |
decidedBy |
no | name of the deciding person in the leading system (up to 200 characters) |
comment |
no | reason or note (up to 2000 characters) |
externalRef |
no | reference of the leading system, for example a workflow id (up to 200 characters) |
curl -X POST https://<your-instance>/api/invoices/<invoiceId>/external-decision \ -H "x-api-key: <your-key>" \ -H "Content-Type: application/json" \ -d '{"decision":"approved","decidedBy":"A. Example","externalRef":"wf-4711"}'The owner of the key needs the right invoices.decide_external, which at present only the Administrator role has.
Answers
Section titled “Answers”| Status | Meaning |
|---|---|
| 200 | body { invoiceId, status, applied }. applied=true: the decision was applied and status is approved or rejected. applied=false: the same decision was already recorded, nothing changed. |
| 400 | invalid body (decision missing or unknown, field too long, unknown field) |
| 401 | key missing, expired or revoked |
| 403 | the owner of the key lacks invoices.decide_external |
| 404 | unknown invoice, outside the key’s access, or not in the company the key is bound to |
| 409 | with a code, see below |
Conflict codes:
code |
Meaning |
|---|---|
approval.external_not_enabled |
approval of this company runs inside fineelik |
approval.external_wrong_status |
the invoice is not waiting for a report; params.status names its status |
approval.external_conflict |
it was already decided differently |
If fineelik itself already rejected the invoice or could not process it (statuses not_an_invoice, duplicate, preflight_rejected, cancelled, rejected, or processing failed for good), a report of rejected answers 200 with applied=false, so that a clearing workflow in the leading system can end. A report of approved for such an invoice answers 409 approval.external_wrong_status. An invoice in the trash answers 404.
Safe to repeat
Section titled “Safe to repeat”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 on an invoice that was already reported is not applied (409, approval.external_conflict). If two reports arrive at the same time, the first wins and the second gets the answer for the state that then applies.
The report appears in the history of the invoice (invoice.status_changed with decidedBy, comment, externalRef and the key as actor) and, with decider, reason and reference, in the approval proof.
Reopening after a report
Section titled “Reopening after a report”- After a rejection (
rejected, reasonapproval_external_rejected), accounting can bring the invoice back into review in fineelik and complete it again. It then waits for a report again, and the leading system starts its own clarification. - After an approval (
approvedwith the reasonapproval_external_approved, and in the payment statespayment_pendingandpayment_approvedwhile that approval is the latest), fineelik locks reopening: 409 with the codeinvoice.reopen_locked_external. Corrections have to be made in the leading system. Otherwise the invoice would wait for a second approval that a workflow no longer sends, and it would never become payable.