Skip to content

Events and export

A leading system learns about changes through a continuous event feed and then reads the export state of the invoice. Both need the right invoices.read. With an API key, only the key’s own company is visible.

Call Effect
GET /api/integration/events?after=&limit=&types= Events in order after the number after (at most 200, default 100). nextCursor is the number for the next call, hasMore tells whether more are waiting.
GET /api/invoices/{id}/export The neutral export state of the invoice (header, vendor, company, amounts as decimal strings, tax lines, payment terms, payment method, accounting, document positions) with revision and dataRevision.
GET /api/integration/invoices/by-dms-guid/{guid} The invoice for a document: invoiceId and status. 404 outside the company.
Type When
invoice.received the invoice was accepted
invoice.status_changed every status change, with previousStatus
invoice.export_changed export-relevant data changed after review without a status change, for example the accounting was corrected or the vendor changed
invoice.processing_failed processing failed for good, see below
agreement.conditions_approved the matching conditions of a contract managed in ELO were approved in fineelik
agreement.conditions_changed the matching conditions of a contract managed in ELO changed, or were submitted, rejected or withdrawn (reason)
agreement.partner_assigned the partner of a contract managed in ELO was assigned to a vendor
agreement.tags_changed the keywords of a contract managed in ELO changed (agreement.tagsText)
agreement.auto_approve_changed the switch for the automatic approval of a contract managed in ELO changed

Events agreement.* carry agreementId, externalGuid (the GUID in ELO) and agreement, the state of the contract when the event is read (the same as GET /api/integration/agreements/{externalGuid}). They come only for contracts handed over from ELO (PUT /api/integration/agreements/{externalGuid}, permission agreements.integration_write). Ignore event types you do not know.

Events are kept for 180 days. If a client has not polled for longer, its next call starts at the oldest event that is left. In rare cases an event becomes visible up to 60 seconds late, so that no event is skipped. You may add companyId to read the events of one company only.

Poll like this: remember the nextCursor of the last answer, call again with after=<nextCursor>, and repeat while hasMore is true.

  • revision changes with everything in the export: also status, reason, the review mark (reviewedAt, reviewedBy), the vendor and the master data of the company.
  • dataRevision covers only what the receiver writes into its own invoice: company.code, documentType, invoiceNumber, invoiceDate, deliveryDate, servicePeriodStart, servicePeriodEnd, dueDate, currency, netAmount, taxAmount, grossAmount, taxLines, paymentTerms, accounting (header), lines with their accounting (also deferral_code), documentPositions and documentLines, the explicit vendor assignment vendor.id (or null) and paymentMethod.erpCode, only when it is set.

Not included are the other vendor master data under vendor, company.id, company.name, company.vatId, invoiceId, dmsGuid, status, statusReason and the review mark.

Write the invoice data only when dataRevision is new. A pure status change (for example “approved”), renaming a vendor or linking it to the ERP for the first time then overwrites no correction that was made in the leading system. Fetch the vendor account separately (for invoice.export_changed with a new vendor.erpVendorNumber, only where it is still missing). A vendor change from A to B does change dataRevision and is taken over even if the account was already filled.

paymentMethod (or null if none is set) names kind (bank_transfer, direct_debit, credit_card, debit_card, online, cash), label, source (extraction, vendor_default, company_default, manual or null) and erpCode.

erpCode is the payment method code in the ERP (Business Central Payment_Method_Code, up to 10 characters), stored with the payment method of the company. It is null while the invoice is before or in review (captured, extracted, review_required), when the payment method has no code, and when source is company_default or null. The ERP then keeps the payment method of the vendor. The receiver writes only codes and never empties an existing value.

A collective vendor (for example “Various creditors EU”) is a normal vendor account in the leading system. In fineelik it carries a region and holds the actual one-off vendors as sub-vendors. Their name, VAT id, address, e-mail and bank details live only in fineelik. The export names the collective vendor under vendor unchanged, because only that one is known to the leading system. The payee of such an invoice is the sub-vendor in fineelik (bank file and payment advice).

  • lines are the booking lines as fineelik codes them (working state after template and review). A booking line can combine several positions of the document.
  • lines[].unit is the code of a unit of measure of the company, or null. The printed unit is in documentLines[].unit.
  • documentLines are the positions as on the document, the unchanged result of reading, ascending by position, with description, quantity, unit (as printed, not a code), unitPrice (full precision), netAmount and taxRate, each a decimal string or null. Positions that belong to no booking line appear here too.
  • lines[].documentPositions lists the position values that this booking line combines. It is empty if the line does not come from a document position (for example added during review).
  • Invoices without read positions return documentLines: [] and documentPositions: [] in every line.
  • The export always shows the current state. A new grouping in review changes only documentPositions. “Reprocess” discards the document positions and reads them again (until then documentLines is empty). Reopening leaves them unchanged. All of this is part of dataRevision.
  • servicePeriodStart and servicePeriodEnd (header, each YYYY-MM-DD or null) give the service period according to the document. A single service date appears as from equals to. If the document names no period, both are null. The invoice date is never used as a substitute. The end is never before the start.
  • lines[].accounting.deferral_code carries the code of the deferral template (Business Central “Deferral Code”, up to 10 characters) with its description. Lines without deferral do not have the key. The deferral of a line with a code starts at the servicePeriodStart of the header, and the number of periods comes from the template in the ERP.

Every pipeline step (pre-check, text recognition, reading, matching) is retried on a temporary error: twice within a minute, then in rounds with growing intervals (for a provider outage for about 16 hours, for a timeout three rounds). While another attempt is pending, the invoice has statusReason <step>_retry: <text>, counts as being processed, and no event is sent.

Only when no automatic attempt is left, statusReason reads <step>_failed: <text> and, at the same moment, invoice.processing_failed is created. The status stays. A reason counts as failed only if its code (before the colon) ends in _failed.

Failed at once are a document that cannot be read (empty, damaged, too large) and processing that waits for a setting (quota used up, key invalid, setting missing). Those pause visibly, are still tried rarely and continue as soon as the settings are saved. The event is sent once for them, not in every round.

The progress in plain terms is in the field processing of the invoice detail (step, state queued, running, retrying, waiting or failed, kind of error, next automatic attempt). Outside processing it is null.