Skip to content

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.

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)
Terminal window
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.

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.

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.

  • After a rejection (rejected, reason approval_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 (approved with the reason approval_external_approved, and in the payment states payment_pending and payment_approved while that approval is the latest), fineelik locks reopening: 409 with the code invoice.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.