Reference: schemas
Money amounts are decimal strings (for example "1234.56"), never floating point numbers. Dates are ISO 8601 strings.
ApiError
Section titled “ApiError”Body of every error answer. message is plain text in German for people and logs: do not parse it. Rely on the HTTP status code and, where present, on code and params.
| Field | Type | Required | Description |
|---|---|---|---|
statusCode |
integer | yes | HTTP status code, repeated in the body. |
message |
string | yes | Plain text in German. Not stable, do not parse it. |
error |
string | no | Name of the HTTP status, for example Not Found. |
code |
string | no | Stable error code where one is assigned, for example approval.external_conflict. Not every error carries a code; use the status code then. |
params |
object | no | Values that belong to the code, for example the status of an invoice. |
issues |
array of object | no | Only on 400 for an invalid request: one entry per invalid field. path names the field, code is the violated validation rule and message is a German explanation. |
issues[].path |
string | no | |
issues[].code |
string | no | |
issues[].message |
string | no | |
retryAfterSeconds |
integer | no | Only on 429 from the rate limit: seconds until the next attempt, the same as the Retry-After header. |
Health
Section titled “Health”Health report of the instance. Further diagnostic fields may be added.
| Field | Type | Required | Description |
|---|---|---|---|
status |
string | yes | ok when database, queue and file storage work, otherwise degraded. One of: ok, degraded. |
checks |
object | no | Result of each check. |
checks.database |
boolean | no | The database answers. |
checks.queue |
boolean | no | The job queue runs and no job has been waiting for too long. |
checks.storage |
boolean | no | The file storage is writable. |
version |
string | no | Release of the running instance, or dev for a development build. |
uptimeSeconds |
integer | no | Seconds since the process started. |
UploadResponse
Section titled “UploadResponse”| Field | Type | Required | Description |
|---|---|---|---|
invoiceId |
string (uuid) | yes | Id of the created invoice, or of the existing one when duplicate is true. |
status |
string | yes | Status of the invoice. See “Invoice status” in the API introduction. 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. |
duplicate |
boolean | yes | true when the file or document was already known in this company. Then nothing new was created and the body names the existing invoice. |
InvoiceList
Section titled “InvoiceList”| Field | Type | Required | Description |
|---|---|---|---|
items |
array of InvoiceListItem | yes | The invoices of the requested page. |
total |
integer | yes | Number of invoices that match the filters, across all pages. Minimum 0. Maximum 9007199254740991. |
page |
integer | yes | Number of this page, starting at 1. Minimum 1. Maximum 9007199254740991. |
pageSize |
integer | yes | Number of invoices per page. Minimum 1. Maximum 9007199254740991. |
InvoiceListItem
Section titled “InvoiceListItem”One invoice in the list. getInvoice returns the full state.
| Field | Type | Required | Description |
|---|---|---|---|
sourceFormat |
string | yes | One of: pdf, image, xrechnung, zugferd, facturx, peppol, en16931, ebinterface, eslog. Default: "pdf". |
sourceProfile |
string, nullable | yes | Default: null. |
isSample |
boolean | yes | Default: false. |
id |
string (uuid) | yes | Id of the invoice. |
companyId |
string (uuid) | yes | Id of the company the invoice belongs to. |
companyName |
string, nullable | no | Name of the company. |
status |
string | yes | Status of the invoice. See “Invoice status” in the API introduction. 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. |
statusReason |
string, nullable | no | Reason for the status, for example approval_external. See “Invoice status” in the API introduction. |
processing |
object, nullable | no | Progress while the invoice is being processed (captured, extracted): step, state, kind of error and time of the next automatic attempt. null outside processing. |
processing.step |
string | yes | One of: preflight, ocr, extract, enrich, einvoice, suggest. |
processing.state |
string | yes | One of: queued, running, retrying, waiting, failed. |
processing.error |
string, nullable | yes | One of: unavailable, timeout, rate_limited, quota, auth, config, document, ai_response, internal, license. |
processing.retryAt |
string (date-time), nullable | yes | |
processing.startedAt |
string (date-time), nullable | yes | |
processing.since |
string (date-time) | yes | |
needsClearance |
boolean | yes | Default: false. |
clearanceNote |
string, nullable | no | |
documentType |
string | yes | invoice or credit_note. One of: invoice, credit_note. |
invoiceNumber |
string, nullable | no | Invoice number as printed on the document. |
invoiceDate |
string (date), nullable | no | Invoice date. |
dueDate |
string (date), nullable | no | Due date. |
currency |
string | yes | Currency of the document (ISO 4217). Pattern: ^[A-Z]{3}$. |
netTotal |
string, nullable | no | Net total as a decimal string. Pattern: ^-?\d+(\.\d+)?$. |
grossTotal |
string, nullable | no | Gross total as a decimal string. Pattern: ^-?\d+(\.\d+)?$. |
vendorId |
string (uuid), nullable | no | Id of the matched vendor, if any. |
vendorName |
string, nullable | no | Name of the matched vendor, if any. |
subVendorName |
string, nullable | no | |
vendorMatchConfidence |
number, nullable | no | Minimum 0. Maximum 1. |
discountDueDate |
string (date), nullable | no | |
discountAmount |
string, nullable | no | Pattern: ^-?\d+(\.\d+)?$. |
paymentMethod |
object, nullable | yes | Default: null. |
paymentMethod.id |
string (uuid) | yes | |
paymentMethod.label |
string | yes | |
paymentMethod.kind |
string | yes | One of: cash, credit_card, bank_transfer, private_outlay, direct_debit, debit_card, online. |
paymentMethod.cardLast4 |
string, nullable | yes | |
deletedAt |
string (date-time), nullable | no | |
deletedByUserId |
string, nullable | no | |
deletedByName |
string, nullable | no | |
deletedFromStatus |
string, nullable | no | 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. |
deleteReason |
string, nullable | no | |
createdAt |
string (date-time) | yes | When fineelik received the document. |
updatedAt |
string (date-time) | yes | When the invoice was last changed. |
InvoiceDetail
Section titled “InvoiceDetail”The full state of an invoice: header and line data, account coding, approval and payment state, references (duplicate, reversal) and validation findings.
| Field | Type | Required | Description |
|---|---|---|---|
sourceFormat |
string | yes | One of: pdf, image, xrechnung, zugferd, facturx, peppol, en16931, ebinterface, eslog. Default: "pdf". |
sourceProfile |
string, nullable | yes | Default: null. |
isSample |
boolean | yes | Default: false. |
intakeItem |
object, nullable | yes | Default: null. |
intakeItem.id |
string (uuid) | yes | |
intakeItem.status |
string | yes | One of: open, assigned, done, processed. |
intakeItem.documentType |
string | yes | One of: invoice, credit_note, delivery_note, order_confirmation, purchase_order, dunning, offer, contract, other, unknown, payment_receipt. |
intakeItem.assignedInvoice |
object, nullable | yes | |
intakeItem.assignedInvoice.id |
string (uuid) | yes | |
intakeItem.assignedInvoice.invoiceNumber |
string, nullable | yes | |
tip |
object, nullable | yes | Default: null. |
tip.amount |
string | yes | |
tip.paidAmount |
string, nullable | yes | |
tip.basis |
string | yes | One of: printed, paid_difference. |
tip.mode |
string | yes | One of: off, notice, line. |
tip.modeSource |
string | yes | One of: sub_vendor, vendor, company. |
tip.state |
string | yes | One of: booked, open, above_limit, ignored. |
tip.proposal |
object | yes | |
tip.proposal.description |
string | yes | |
tip.proposal.taxRate |
string | yes | |
tip.proposal.netAmount |
string | yes | |
tip.proposal.taxAmount |
string | yes | |
tip.proposal.grossAmount |
string | yes | |
tip.proposal.dimensions |
object | yes | |
einvoiceReview |
object, nullable | yes | Default: null. |
einvoiceReview.formalMode |
string | yes | One of: hint, block. |
einvoiceReview.formalChecked |
boolean | yes | |
einvoiceReview.formalValid |
boolean, nullable | yes | |
einvoiceReview.formalErrorCount |
integer | yes | Minimum 0. Maximum 9007199254740991. |
einvoiceReview.formalAcceptedAt |
string (date-time), nullable | yes | |
einvoiceReview.formalAcceptedByName |
string, nullable | yes | |
einvoiceReview.formalBlocking |
boolean | yes | |
einvoiceReview.prepaidAmount |
string, nullable | yes | Pattern: ^-?\d+(\.\d+)?$. |
einvoiceReview.prepaymentRecorded |
boolean | yes | |
matchReview |
object, nullable | yes | Default: null. |
matchReview.mode |
string | yes | One of: clearance, block. |
matchReview.deviations |
integer | yes | Minimum 0. Maximum 9007199254740991. |
matchReview.quantityDeviations |
integer | yes | Minimum 0. Maximum 9007199254740991. |
matchReview.orderDeviations |
integer | yes | Minimum 0. Maximum 9007199254740991. |
matchReview.confirmed |
boolean | yes | |
matchReview.confirmedAt |
string (date-time), nullable | yes | |
matchReview.confirmedByName |
string, nullable | yes | |
matchReview.blocking |
boolean | yes | |
agreementMatch |
object, nullable | yes | Contract block (module “Contracts”): the assignments of the invoice to contracts and their check. null without the module. An API key is never a named viewer: for a confidential contract an assignment has visibility limited, then contract, payment line, amounts, tolerance, score and the parameters of the checks are empty and only the result and the check codes remain. Default: null. |
agreementMatch.mode |
string | yes | One of: clearance, block. |
agreementMatch.links |
array of object | yes | Active assignments, also suggestions. |
agreementMatch.links[].id |
string (uuid) | yes | |
agreementMatch.links[].visibility |
string | yes | One of: full, limited. |
agreementMatch.links[].confidential |
boolean | yes | |
agreementMatch.links[].agreement |
object, nullable | yes | |
agreementMatch.links[].agreement.id |
string (uuid) | yes | |
agreementMatch.links[].agreement.number |
string | yes | |
agreementMatch.links[].agreement.title |
string | yes | |
agreementMatch.links[].agreement.vendorId |
string (uuid), nullable | yes | |
agreementMatch.links[].agreement.vendorName |
string, nullable | yes | |
agreementMatch.links[].agreement.counterpartyName |
string, nullable | yes | |
agreementMatch.links[].agreement.managedBy |
string | yes | One of: fineelik, elo. Default: "fineelik". |
agreementMatch.links[].paymentLine |
object, nullable | yes | |
agreementMatch.links[].paymentLine.id |
string (uuid) | yes | |
agreementMatch.links[].paymentLine.description |
string | yes | |
agreementMatch.links[].paymentLine.cycle |
string | yes | One of: one_time, daily, weekly, biweekly, monthly, quarterly, half_yearly, yearly. |
agreementMatch.links[].paymentLine.kind |
string | yes | One of: fixed, variable. |
agreementMatch.links[].paymentLine.objectNumber |
string, nullable | yes | |
agreementMatch.links[].matchSource |
string | yes | One of: auto, suggested, manual. |
agreementMatch.links[].matchRule |
string | yes | One of: contract_number, match_key, object_number, score, manual. |
agreementMatch.links[].matchedKey |
string, nullable | yes | |
agreementMatch.links[].score |
number, nullable | yes | |
agreementMatch.links[].reasons |
array of object | yes | |
agreementMatch.links[].reasons[].code |
string | yes | One of: contract_number, match_key, object_number, vendor, amount_exact, amount_in_tolerance, amount_near, period_cycle, in_term, weak_key, several_candidates, vendor_mismatch, vendor_unknown. |
agreementMatch.links[].reasons[].params |
object | yes | |
agreementMatch.links[].periodStart |
string (date), nullable | yes | |
agreementMatch.links[].periodEnd |
string (date), nullable | yes | |
agreementMatch.links[].periodCount |
integer | yes | Minimum -9007199254740991. Maximum 9007199254740991. |
agreementMatch.links[].amountBasis |
string | yes | One of: net, gross. |
agreementMatch.links[].currency |
string | yes | |
agreementMatch.links[].expectedAmount |
string, nullable | yes | Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].actualAmount |
string, nullable | yes | Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].deviationAmount |
string, nullable | yes | Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].deviationPercent |
string, nullable | yes | |
agreementMatch.links[].allowedUpAmount |
string, nullable | yes | Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].allowedDownAmount |
string, nullable | yes | Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].result |
string | yes | One of: ok, deviation, unchecked. |
agreementMatch.links[].checks |
array of object | yes | |
agreementMatch.links[].checks[].code |
string | yes | One of: amount_in_tolerance, amount_above, amount_below, amount_missing, no_payment_line, positions_unassigned, currency_mismatch, before_start, after_end, terminated, not_active, second_invoice_in_period, total_value_exceeded, total_value_near, variable_amount_unchecked, index_clause_present, price_increase, price_increase_over_limit. |
agreementMatch.links[].checks[].severity |
string | yes | One of: ok, info, deviation. |
agreementMatch.links[].checks[].params |
object | yes | |
agreementMatch.links[].positions |
array of integer | yes | |
agreementMatch.links[].confirmed |
boolean | yes | |
agreementMatch.links[].confirmedAt |
string (date-time), nullable | yes | |
agreementMatch.links[].confirmedByName |
string, nullable | yes | |
agreementMatch.links[].deviationAccepted |
boolean | yes | |
agreementMatch.links[].deviationAcceptedAt |
string (date-time), nullable | yes | |
agreementMatch.links[].deviationAcceptedByName |
string, nullable | yes | |
agreementMatch.links[].checkedAt |
string (date-time) | yes | |
agreementMatch.deviations |
integer | yes | Minimum 0. Maximum 9007199254740991. |
agreementMatch.blocking |
boolean | yes | true when the company blocks on deviations and a deviation is not confirmed yet. |
agreementMatch.outcome |
string | yes | Result for the whole invoice: ok, deviation, unchecked, suggested, partial (not fully assigned) or none. One of: ok, deviation, unchecked, suggested, partial, none. |
agreementMatch.autoApproval |
object, nullable | yes | Decision of the automatic approval when the approval started inside fineelik, or null when none was taken (before the start, without contract, or when the approval runs in the leading system). blockers lists the reasons against as codes, see agreementMatch.blockers in InvoiceExport. |
agreementMatch.autoApproval.possible |
boolean | yes | |
agreementMatch.autoApproval.autoApproved |
boolean | yes | |
agreementMatch.autoApproval.decidedAt |
string (date-time) | yes | |
agreementMatch.autoApproval.outcome |
string | yes | One of: ok, deviation, unchecked, suggested, partial, none. |
agreementMatch.autoApproval.blockers |
array of string | yes | |
dmsTransfer |
object, nullable | yes | Default: null. |
dmsTransfer.state |
string | yes | One of: waiting, failed. |
dmsTransfer.attempts |
integer | yes | Minimum 0. Maximum 9007199254740991. |
dmsTransfer.lastError |
string, nullable | yes | |
dmsTransfer.nextAttemptAt |
string (date-time), nullable | yes | |
id |
string (uuid) | yes | Id of the invoice. |
status |
string | yes | Status of the invoice. See “Invoice status” in the API introduction. 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. |
statusReason |
string, nullable | no | Reason for the status, for example approval_external. See “Invoice status” in the API introduction. |
processing |
object, nullable | no | Progress while the invoice is being processed (captured, extracted): step, state (queued, running, retrying, waiting, failed), kind of error and time of the next automatic attempt. null outside processing. |
processing.step |
string | yes | One of: preflight, ocr, extract, enrich, einvoice, suggest. |
processing.state |
string | yes | One of: queued, running, retrying, waiting, failed. |
processing.error |
string, nullable | yes | One of: unavailable, timeout, rate_limited, quota, auth, config, document, ai_response, internal, license. |
processing.retryAt |
string (date-time), nullable | yes | |
processing.startedAt |
string (date-time), nullable | yes | |
processing.since |
string (date-time) | yes | |
suggestionsPending |
boolean | no | |
pageRotation |
integer | no | Minimum 0. Maximum 270. |
captureChannel |
string | yes | Channel through which the document arrived (for example upload or dms). One of: dms, email, upload, api, expense, import, reversal. |
externalDocumentLink |
object, nullable | yes | Default: null. |
externalDocumentLink.provider |
string | yes | One of: elo. |
externalDocumentLink.url |
string (uri) | yes | |
documentType |
string | yes | invoice or credit_note. One of: invoice, credit_note. |
invoiceNumber |
string, nullable | no | Invoice number as printed on the document. |
invoiceDate |
string (date), nullable | no | Invoice date. |
dueDate |
string (date), nullable | no | Due date. |
dueDateSource |
string, nullable | no | One of: extraction, payment_term, vendor_default, invoice_date, manual. |
paymentMethod |
object, nullable | yes | Default: null. |
paymentMethod.id |
string (uuid) | yes | |
paymentMethod.label |
string | yes | |
paymentMethod.kind |
string | yes | One of: cash, credit_card, bank_transfer, private_outlay, direct_debit, debit_card, online. |
paymentMethod.cardLast4 |
string, nullable | yes | |
paymentMethodSource |
string, nullable | no | One of: extraction, vendor_default, company_default, manual. |
paymentHint |
object, nullable | yes | Default: null. |
paymentHint.method |
string | yes | One of: bank_transfer, direct_debit, credit_card, debit_card, online, cash, unknown. |
paymentHint.status |
string | yes | One of: open, paid, will_be_debited, unknown. |
paymentHint.cardLast4 |
string, nullable | yes | |
paymentHint.evidence |
string, nullable | yes | |
paymentMethodWarnings |
array of string | yes | Default: []. |
servicePeriodStart |
string (date), nullable | no | Start of the service period according to the document, if named. |
servicePeriodEnd |
string (date), nullable | no | End of the service period according to the document, if named. |
currency |
string | yes | Currency of the document (ISO 4217). Pattern: ^[A-Z]{3}$. |
netTotal |
string, nullable | no | Net total as a decimal string. Pattern: ^-?\d+(\.\d+)?$. |
grossTotal |
string, nullable | no | Gross total as a decimal string. Pattern: ^-?\d+(\.\d+)?$. |
taxAmounts |
array of object | yes | Tax amounts by tax rate. |
taxAmounts[].taxRate |
string | yes | Pattern: ^-?\d+(\.\d+)?$. |
taxAmounts[].netAmount |
string | yes | Pattern: ^-?\d+(\.\d+)?$. |
taxAmounts[].taxAmount |
string | yes | Pattern: ^-?\d+(\.\d+)?$. |
reverseCharge |
boolean | yes | Default: false. |
reverseChargeSource |
string | yes | One of: manual, sub_vendor, vendor, group, country, document. Default: "document". |
reverseChargeInputs |
object | yes | Default: {"override":"auto","documentHint":false,"subVendorOverride":null,"vendorOverride":null,"vendorBusinessPostingGroup":null,"groupDefaults":{},"countryDefault":null}. |
reverseChargeInputs.override |
string | yes | One of: auto, ignore, force. |
reverseChargeInputs.documentHint |
boolean | yes | |
reverseChargeInputs.subVendorOverride |
string, nullable | yes | One of: auto, ignore, force. |
reverseChargeInputs.vendorOverride |
string, nullable | yes | One of: auto, ignore, force. |
reverseChargeInputs.vendorBusinessPostingGroup |
string, nullable | yes | |
reverseChargeInputs.groupDefaults |
object | yes | |
reverseChargeInputs.countryDefault |
boolean, nullable | yes | Default: null. |
paymentTerms |
object, nullable | no | The payment term that fineelik applies (the best valid one). |
paymentTerms.dueDate |
string (date), nullable | no | |
paymentTerms.discountDays |
integer, nullable | no | Minimum 0. Maximum 9007199254740991. |
paymentTerms.discountPercent |
string, nullable | no | Pattern: ^-?\d+(\.\d+)?$. |
paymentTerms.discountAmount |
string, nullable | no | Pattern: ^-?\d+(\.\d+)?$. |
paymentTermsList |
array of object | yes | |
paymentTermsList[].rank |
integer | yes | Minimum 1. Maximum 9007199254740991. |
paymentTermsList[].dueDate |
string (date), nullable | no | |
paymentTermsList[].discountDays |
integer, nullable | no | Minimum 0. Maximum 9007199254740991. |
paymentTermsList[].discountPercent |
string | yes | Pattern: ^-?\d+(\.\d+)?$. |
paymentTermsList[].discountAmount |
string, nullable | no | Pattern: ^-?\d+(\.\d+)?$. |
paymentTermsList[].source |
string | yes | One of: extraction, manual, erp_default. |
originalPaymentTerms |
array of object | yes | |
originalPaymentTerms[].rank |
integer | yes | Minimum 1. Maximum 9007199254740991. |
originalPaymentTerms[].dueDate |
string (date), nullable | no | |
originalPaymentTerms[].discountDays |
integer, nullable | no | Minimum 0. Maximum 9007199254740991. |
originalPaymentTerms[].discountPercent |
string | yes | Pattern: ^-?\d+(\.\d+)?$. |
originalPaymentTerms[].discountAmount |
string, nullable | no | Pattern: ^-?\d+(\.\d+)?$. |
orders |
array of object | yes | |
orders[].orderNumber |
string | yes | |
orders[].orderDate |
string (date), nullable | no | |
company |
object | yes | The company the invoice belongs to. |
company.id |
string (uuid) | yes | |
company.code |
string | yes | |
company.name |
string | yes | |
company.vatId |
string, nullable | no | |
company.defaultCurrency |
string | no | Pattern: ^[A-Z]{3}$. |
company.countryCode |
string, nullable | no | |
recipient |
object | yes | |
recipient.name |
string, nullable | yes | |
recipient.vatId |
string, nullable | yes | |
recipient.taxNumber |
string, nullable | yes | Default: null. |
recipient.state |
string | yes | One of: match, not_on_document, mismatch, other_company. |
recipient.taxNumberDiffers |
object, nullable | yes | Default: null. |
recipient.taxNumberDiffers.printed |
string | yes | |
recipient.taxNumberDiffers.own |
string | yes | |
recipient.suggestedCompany |
object, nullable | yes | |
recipient.suggestedCompany.id |
string (uuid) | yes | |
recipient.suggestedCompany.name |
string | yes | |
vendor |
object, nullable | no | The matched vendor, if any. |
vendor.id |
string (uuid) | yes | |
vendor.name |
string | yes | |
vendor.vatId |
string, nullable | no | |
vendor.matchType |
string, nullable | no | |
vendor.matchConfidence |
number, nullable | no | Minimum 0. Maximum 1. |
vendor.paymentDefaults |
object, nullable | no | |
vendor.paymentDefaults.termDays |
integer, nullable | no | Minimum 0. Maximum 9007199254740991. |
vendor.paymentDefaults.discountPercent |
string, nullable | no | Pattern: ^-?\d+(\.\d+)?$. |
vendor.paymentDefaults.discountDays |
integer, nullable | no | Minimum 0. Maximum 9007199254740991. |
subVendor |
object, nullable | no | |
subVendor.id |
string (uuid) | yes | |
subVendor.code |
string | yes | |
subVendor.name |
string | yes | |
subVendor.vatId |
string, nullable | no | |
subVendor.countryCode |
string, nullable | no | |
subVendor.city |
string, nullable | no | |
subVendor.hasIban |
boolean | yes | |
collectiveSuggestion |
object, nullable | no | |
collectiveSuggestion.vendorId |
string (uuid) | yes | |
collectiveSuggestion.vendorName |
string | yes | |
collectiveSuggestion.scope |
string | yes | One of: domestic, eu, non_eu, all. |
collectiveSuggestion.proposed |
object | yes | |
collectiveSuggestion.proposed.name |
string | yes | Up to 200 characters. |
collectiveSuggestion.proposed.code |
string | no | Up to 50 characters. |
collectiveSuggestion.proposed.vatId |
string, nullable | no | Up to 50 characters. |
collectiveSuggestion.proposed.countryCode |
string, nullable | no | Up to 2 characters. |
collectiveSuggestion.proposed.street |
string, nullable | no | Up to 200 characters. |
collectiveSuggestion.proposed.zip |
string, nullable | no | Up to 20 characters. |
collectiveSuggestion.proposed.city |
string, nullable | no | Up to 100 characters. |
collectiveSuggestion.proposed.email |
string (email), nullable | no | |
collectiveSuggestion.proposed.iban |
string, nullable | no | Up to 42 characters. Pattern: ^[A-Za-z]{2}[0-9A-Za-z ]+$. |
collectiveSuggestion.proposed.bic |
string, nullable | no | |
collectiveSuggestion.proposed.reverseChargeOverride |
string | no | One of: auto, ignore, force. |
collectiveSuggestion.proposed.tipHandling |
string | no | One of: auto, off, notice, line. |
collectiveSuggestion.existingSubVendorId |
string (uuid), nullable | no | |
ordererName |
string, nullable | no | |
vendorPrinted |
object | yes | |
vendorPrinted.name |
string, nullable | no | |
vendorPrinted.vatId |
string, nullable | no | |
vendorPrinted.taxNumber |
string, nullable | no | |
vendorPrinted.street |
string, nullable | no | |
vendorPrinted.zip |
string, nullable | no | |
vendorPrinted.city |
string, nullable | no | |
vendorPrinted.countryCode |
string, nullable | no | |
vendorPrinted.bankAccounts |
array of object | yes | Default: []. |
vendorPrinted.bankAccounts[].iban |
string | yes | |
vendorPrinted.bankAccounts[].bic |
string, nullable | yes | |
vendorCheck |
object, nullable | no | |
vendorCheck.subject |
string | yes | One of: vendor, sub_vendor. |
vendorCheck.subjectId |
string (uuid) | yes | |
vendorCheck.vendorId |
string (uuid) | yes | |
vendorCheck.ledByErp |
boolean | yes | |
vendorCheck.bankFromErp |
boolean | yes | |
vendorCheck.vendorIbanLast4 |
string, nullable | yes | |
vendorCheck.iban |
string | yes | One of: match, unknown, vendor_without_iban, pending, none_printed. |
vendorCheck.vatId |
string | yes | One of: match, differs, vendor_without_vat_id, none_printed. |
vendorCheck.name |
string | yes | One of: match, differs. |
lineItems |
array of object | yes | Line items with their account coding (the working state of the review). |
lineItems[].id |
string (uuid) | yes | |
lineItems[].position |
integer | yes | Minimum 0. Maximum 9007199254740991. |
lineItems[].description |
string | yes | |
lineItems[].itemNo |
string, nullable | no | |
lineItems[].quantity |
string, nullable | no | Pattern: ^-?\d+(\.\d+)?$. |
lineItems[].unit |
string, nullable | no | |
lineItems[].unitLabel |
string, nullable | no | |
lineItems[].unitPrice |
string, nullable | no | Pattern: ^-?\d+(\.\d+)?$. |
lineItems[].netAmount |
string | yes | Pattern: ^-?\d+(\.\d+)?$. |
lineItems[].taxRate |
string | yes | Pattern: ^-?\d+(\.\d+)?$. |
lineItems[].originalLineItemIds |
array of string (uuid) | yes | |
lineItems[].isTip |
boolean | no | |
lineItems[].dimensions |
object | yes | |
headerDimensions |
object | yes | Account coding on header level. The key is the dimension key, the value holds code and label. |
originalLineItems |
array of object | yes | |
originalLineItems[].id |
string (uuid) | yes | |
originalLineItems[].position |
integer | yes | Minimum 0. Maximum 9007199254740991. |
originalLineItems[].itemNo |
string, nullable | no | |
originalLineItems[].description |
string | yes | |
originalLineItems[].quantity |
string, nullable | no | Pattern: ^-?\d+(\.\d+)?$. |
originalLineItems[].unit |
string, nullable | no | |
originalLineItems[].unitPrice |
string, nullable | no | Pattern: ^-?\d+(\.\d+)?$. |
originalLineItems[].netAmount |
string, nullable | no | Pattern: ^-?\d+(\.\d+)?$. |
originalLineItems[].taxRate |
string, nullable | no | Pattern: ^-?\d+(\.\d+)?$. |
originalLineItems[].appliedRule |
object, nullable | no | |
originalLineItems[].appliedRule.blueprintId |
string (uuid) | yes | |
originalLineItems[].appliedRule.positionKey |
string | yes | |
originalLineItems[].appliedRule.groupId |
string (uuid), nullable | yes | |
originalLineItems[].appliedRule.bookingText |
string, nullable | yes | |
originalLineItems[].appliedRule.label |
string | yes | |
validation |
object | yes | |
validation.valid |
boolean | yes | |
validation.issues |
array of object | yes | |
validation.issues[].code |
string | yes | |
validation.issues[].severity |
string | yes | One of: error, warning. |
validation.issues[].message |
string | yes | |
validation.issues[].field |
string, nullable | no | |
validation.issues[].lineNumber |
integer, nullable | no | Minimum 1. Maximum 9007199254740991. |
validation.issues[].dimensionKey |
string, nullable | no | |
validation.issues[].params |
object, nullable | no | |
fieldConfidences |
object | yes | |
reviewedFields |
array of string | yes | |
blueprint |
object | yes | |
blueprint.applied |
boolean | yes | |
blueprint.blueprintId |
string (uuid), nullable | no | |
blueprint.matchedRuleCount |
integer | yes | Minimum 0. Maximum 9007199254740991. |
blueprint.suggestedLineItemIds |
array of string (uuid) | yes | |
blueprint.ruleValues |
array of object | yes | |
blueprint.ruleValues[].lineItemId |
string (uuid) | yes | |
blueprint.ruleValues[].dimensionKey |
string | yes | |
blueprint.ruleValues[].code |
string | yes | |
duplicate |
object | yes | |
duplicate.state |
string | yes | One of: disabled, no_key, clear, dismissed, open. |
duplicate.matchKind |
string, nullable | no | One of: invoice_number, date_and_amount. |
duplicate.key |
string, nullable | no | |
duplicate.dismissedAt |
string (date-time), nullable | no | |
duplicate.original |
object, nullable | no | |
duplicate.original.id |
string (uuid) | yes | |
duplicate.original.invoiceNumber |
string, nullable | no | |
duplicate.original.invoiceDate |
string (date), nullable | no | |
duplicate.original.grossAmount |
string, nullable | no | Pattern: ^-?\d+(\.\d+)?$. |
duplicate.original.status |
string | yes | 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. |
duplicate.original.vendorName |
string, nullable | no | |
reversal |
object | yes | |
reversal.reversalOf |
object, nullable | no | |
reversal.reversalOf.id |
string (uuid) | yes | |
reversal.reversalOf.invoiceNumber |
string, nullable | no | |
reversal.reversedBy |
object, nullable | no | |
reversal.reversedBy.id |
string (uuid) | yes | |
reversal.reversedBy.invoiceNumber |
string, nullable | no | |
supersededAdvice |
object, nullable | yes | |
supersededAdvice.number |
string | yes | |
supersededAdvice.sentAt |
string (date-time) | yes | |
posting |
object, nullable | no | |
posting.documentNumber |
string, nullable | yes | |
posting.postedAt |
string, nullable | yes | |
posting.deviation |
object, nullable | yes | |
posting.deviation.noticeId |
string | yes | |
posting.deviation.readAt |
string, nullable | yes | |
posting.deviation.payload |
object | yes | |
posting.deviation.payload.documentNumber |
string | yes | |
posting.deviation.payload.postedAt |
string (date-time) | yes | |
posting.deviation.payload.accountNotComparable |
boolean | yes | |
posting.deviation.payload.deviations |
array of one of object, object | yes | |
deletedAt |
string (date-time), nullable | no | |
deletedByUserId |
string, nullable | no | |
deletedByName |
string, nullable | no | |
deletedFromStatus |
string, nullable | no | 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. |
deleteReason |
string, nullable | no | |
createdAt |
string (date-time) | yes | When fineelik received the document. |
updatedAt |
string (date-time) | yes | When the invoice was last changed. |
InvoiceHistory
Section titled “InvoiceHistory”| Field | Type | Required | Description |
|---|---|---|---|
items |
array of object | yes | History entries, newest first. At most the latest 200 entries are returned. |
items[].id |
string (uuid) | yes | Id of the entry. |
items[].action |
string | yes | Kind of change, for example invoice.status_changed or invoice.line_items_replaced. |
items[].actorUserId |
string, nullable | yes | Id of the user who acted. null when a machine acted. |
items[].actorName |
string, nullable | yes | Name of the user, if it can still be resolved. |
items[].actorApiKeyId |
string, nullable | yes | Id of the API key that acted. null when a user acted. |
items[].before |
object, nullable | yes | State before the change. The keys depend on the action. |
items[].after |
object, nullable | yes | State after the change. The keys depend on the action. |
items[].metadata |
object, nullable | yes | Further details. For a decision reported from outside this holds decidedBy, comment and externalRef. |
items[].createdAt |
string (date-time) | yes | When the change happened. |
ExternalDecisionRequest
Section titled “ExternalDecisionRequest”| Field | Type | Required | Description |
|---|---|---|---|
decision |
string | yes | approved or rejected. One of: approved, rejected. |
decidedBy |
string | no | Name of the person who decided in the leading system (up to 200 characters). fineelik does not know this person as a user, the name is kept as plain text. Up to 200 characters. |
comment |
string | no | Reason or note (up to 2000 characters). Up to 2000 characters. |
externalRef |
string | no | Reference of the leading system, for example a workflow id (up to 200 characters). Kept for the history only. Up to 200 characters. |
ExternalDecisionResponse
Section titled “ExternalDecisionResponse”| Field | Type | Required | Description |
|---|---|---|---|
invoiceId |
string (uuid) | yes | Id of the invoice. |
status |
string | yes | Status after the call: approved or rejected. 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. |
applied |
boolean | yes | true: the decision was applied now. false: the same decision was already on record and nothing changed. |
IntegrationEvent
Section titled “IntegrationEvent”One event about an invoice.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Sequence number of the event, as a string. Unique and ascending. Use it as the cursor for the next call and to recognize an event that arrives twice. Pattern: ^\d{1,19}$. |
type |
string | yes | Kind of event: - invoice.received: the document was accepted (upload, e-mail or hand over from the document management system). - invoice.status_changed: every change of status, with previousStatus. - invoice.export_changed: data relevant for the export changed after review without a change of status, for example the account coding was corrected or the vendor changed. - invoice.processing_failed: processing (preflight, text recognition, extraction, matching) failed after the last automatic attempt, or waits for a missing setting. The status stays, statusReason is <step>_failed: <text>. Intermediate errors before another attempt (<step>_retry) create no event. One of: invoice.received, invoice.status_changed, invoice.export_changed, invoice.processing_failed. |
occurredAt |
string (date-time) | yes | When the event was created. |
invoiceId |
string (uuid) | yes | Id of the invoice. |
companyId |
string (uuid) | yes | Id of the company of the invoice. |
companyCode |
string | yes | Code of the company. |
dmsGuid |
string, nullable | yes | GUID of the document in the document management system (for example ELO) when the invoice came from there, otherwise null. |
status |
string | yes | Status of the invoice after the event. 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. |
previousStatus |
string, nullable | yes | Only for invoice.status_changed: the status before. Otherwise null. 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. |
statusReason |
string, nullable | yes | Reason for the status after the event, if any. |
agreementMatch |
object, nullable | yes | Contract block (module “Contracts”) as it is when the event is fetched or delivered, the same as agreementMatch in InvoiceExport. null without the module, without assignment, or when it could not be determined (then do not approve automatically). Confidential contracts: only confidential and result per entry, no number and no amounts. Default: null. |
agreementMatch.outcome |
string | yes | Result for the whole invoice: ok (fully assigned, within the tolerance, nothing open), deviation, unchecked (an assignment could not be checked, for example without amount), suggested (only a suggestion, or an open suggestion beside the assignment), partial (not every position is assigned, or positions are assigned twice) or none. One of: ok, deviation, unchecked, suggested, partial, none. |
agreementMatch.autoApprovalPossible |
boolean | yes | true when every rule of the automatic approval holds, so blockers is empty. |
agreementMatch.blockers |
array of string | yes | Reasons against the automatic approval, as codes in a fixed order: module_not_licensed, company_auto_approve_off, match_failed, outcome_none, outcome_suggested, outcome_partial, outcome_unchecked, outcome_deviation, agreement_not_active, conditions_not_approved, conditions_pending, agreement_auto_approve_off, vendor_mismatch, amount_missing, max_amount_exceeded, first_invoice_of_vendor, bank_account_deviates, bank_account_recently_changed, duplicate_suspected, open_error_findings, credit_note, currency_mismatch, second_invoice_in_period, needs_clearance, order_match_deviation, sample_due. Treat unknown codes as a reason against. |
agreementMatch.links |
array of object | yes | One entry per effective assignment (automatic, manual or confirmed). |
agreementMatch.links[].confidential |
boolean | yes | true for a confidential contract. Then every field except result is null. |
agreementMatch.links[].agreementId |
string (uuid), nullable | yes | Id of the contract in fineelik. |
agreementMatch.links[].number |
string, nullable | yes | Number of the contract in fineelik. |
agreementMatch.links[].externalNumber |
string, nullable | yes | Number of the contract at the partner or in the leading system, or null. |
agreementMatch.links[].matchSource |
string, nullable | yes | auto, suggested (confirmed by a person) or manual. One of: auto, suggested, manual. |
agreementMatch.links[].result |
string | yes | Result of the check: ok, deviation or unchecked. One of: ok, deviation, unchecked. |
agreementMatch.links[].currency |
string, nullable | yes | Currency of the contract (ISO 4217). |
agreementMatch.links[].expectedAmount |
string, nullable | yes | Expected amount for the period of the invoice (net or gross as set in the contract). Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].actualAmount |
string, nullable | yes | Actual amount of the invoice or of its assigned positions. Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].deviationAmount |
string, nullable | yes | Actual minus expected amount (positive above the expected amount). Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].deviationPercent |
string, nullable | yes | Deviation in percent of the expected amount, two decimals. |
agreementMatch.links[].allowedUpAmount |
string, nullable | yes | Allowed deviation upwards as an amount. Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].allowedDownAmount |
string, nullable | yes | Allowed deviation downwards as an amount. Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].externalGuid |
string, nullable | yes | Default: null. |
IntegrationEvents
Section titled “IntegrationEvents”| Field | Type | Required | Description |
|---|---|---|---|
items |
array of one of IntegrationEvent, AgreementIntegrationEvent | yes | Events in ascending order of id. |
nextCursor |
string | yes | Id of the last event in this answer, or the after value of the call when nothing was found. Pass it as after in the next call. Pattern: ^\d{1,19}$. |
hasMore |
boolean | yes | true when more events wait. Call again at once with nextCursor. |
AgreementIntegrationEvent
Section titled “AgreementIntegrationEvent”One event about a contract managed in ELO. agreement is the state when the event is fetched or delivered (see AgreementEloState), null when the contract no longer exists or the module is not licensed.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Sequence number of the event, as a string, from the same stream as the invoice events. Pattern: ^\d{1,19}$. |
type |
string | yes | Kind of event (only for contracts managed in ELO): - agreement.conditions_approved: the matching conditions were approved in fineelik. - agreement.conditions_changed: the conditions changed (in fineelik or by a hand over from ELO), were submitted for approval, rejected or withdrawn; see reason. - agreement.partner_assigned: the partner was assigned to a vendor, or the assignment changed. - agreement.tags_changed: the keywords changed (agreement.tagsText). - agreement.auto_approve_changed: the switch for the automatic approval changed. One of: agreement.conditions_approved, agreement.conditions_changed, agreement.partner_assigned, agreement.tags_changed, agreement.auto_approve_changed. |
occurredAt |
string (date-time) | yes | |
agreementId |
string (uuid) | yes | Id of the contract in fineelik. |
companyId |
string (uuid) | yes | |
companyCode |
string | yes | |
externalSystem |
string, nullable | yes | |
externalGuid |
string, nullable | yes | GUID of the contract in ELO. |
status |
string | yes | State of the contract in fineelik at the time of the event. One of: draft, in_negotiation, in_approval, approved, signed, active, in_termination, terminated, ended. |
reason |
string, nullable | yes | Occasion: elo_handover, fineelik_edit, submitted, rejected, withdrawn, partner_mapping or extraction; null for an approval. |
agreement |
all of AgreementEloState | yes |
AgreementEloState
Section titled “AgreementEloState”State of a contract that is managed in ELO Contract (module “Contracts”), for the leading system. It holds only what ELO has anyway (status, identifiers) and the fields that belong to fineelik: the vendor the partner is assigned to, net or gross, tolerances, automatic approval, object numbers, keywords, match keys and whether the matching conditions are approved in fineelik. No document content, no title and no summary, so the same applies to confidential contracts.
automationReady is true when nothing at the contract speaks against the automatic approval of invoices (status in ELO COMPLETED, conditions approved in fineelik, switch on at the contract and in the company, partner assigned). The rules per invoice (bank account, duplicate, sample, …) come on top and are in agreementMatch of the invoice.
| Field | Type | Required | Description |
|---|---|---|---|
agreementId |
string (uuid) | yes | Id of the contract in fineelik. |
companyId |
string (uuid) | yes | |
companyCode |
string | yes | |
number |
string | yes | Number of the contract in fineelik. |
externalSystem |
string | yes | |
externalGuid |
string | yes | GUID of the contract in ELO (Sord.guid), in ELO notation. |
externalRevision |
string, nullable | yes | Revision of the last accepted hand over (as sent in revision). |
externalChangedAt |
string (date-time), nullable | yes | Time of change in ELO of the last accepted hand over. |
status |
string | yes | State in fineelik, mapped from the status in ELO (COMPLETED is active). It comes only from ELO. One of: draft, in_negotiation, in_approval, approved, signed, active, in_termination, terminated, ended. |
eloStatus |
string, nullable | yes | Status key in ELO as sent, for example COMPLETED. |
confidential |
boolean | yes | |
partner |
object, nullable | yes | Contract partner (first PARTNER of the hand over) and the vendor it is assigned to, or null without partner. |
partner.externalKey |
string | yes | |
partner.name |
string, nullable | yes | |
partner.assigned |
boolean | yes | |
partner.vendorId |
string (uuid), nullable | yes | |
partner.vendorName |
string, nullable | yes | |
partner.erpVendorNumber |
string, nullable | yes | |
partner.source |
string, nullable | yes | One of: auto, user. |
partner.unresolvedReason |
string, nullable | yes | One of: none, ambiguous. |
amountBasis |
string | yes | One of: net, gross. |
tolerance |
object | yes | |
tolerance.upPercent |
string, nullable | yes | Pattern: ^\d{1,3}(\.\d{1,2})?$. |
tolerance.downPercent |
string, nullable | yes | Pattern: ^\d{1,3}(\.\d{1,2})?$. |
tolerance.upAmount |
string, nullable | yes | Pattern: ^-?\d+(\.\d{1,2})?$. |
tolerance.downAmount |
string, nullable | yes | Pattern: ^-?\d+(\.\d{1,2})?$. |
autoApprove |
boolean | yes | |
noPayments |
boolean | yes | |
tags |
array of string | yes | Confirmed keywords of the contract (fineelik list), alphabetical. |
tagsText |
string | yes | The same keywords as one text separated by ; , for the text field in ELO. |
matchKeys |
array of string | yes | Identifiers fineelik uses to assign invoices (number at the partner, customer number, object numbers). |
responsible |
object, nullable | yes | Responsible person in fineelik with e-mail, or null. |
responsible.userId |
string | yes | |
responsible.email |
string, nullable | yes | |
secondResponsible |
object, nullable | yes | |
secondResponsible.userId |
string | yes | |
secondResponsible.email |
string, nullable | yes | |
paymentLines |
array of object | yes | Payment lines with the fields that belong to fineelik, keyed by externalKey (the lineKey of the hand over, otherwise pos:<n>). removed lines were removed in ELO; they stay in fineelik because invoices refer to them. |
paymentLines[].externalKey |
string, nullable | yes | |
paymentLines[].sequence |
integer | yes | Minimum -9007199254740991. Maximum 9007199254740991. |
paymentLines[].removed |
boolean | yes | |
paymentLines[].kind |
string | yes | One of: fixed, variable. |
paymentLines[].objectNumber |
string, nullable | yes | |
paymentLines[].tolerance |
object | yes | |
paymentLines[].tolerance.upPercent |
string, nullable | yes | Pattern: ^\d{1,3}(\.\d{1,2})?$. |
paymentLines[].tolerance.downPercent |
string, nullable | yes | Pattern: ^\d{1,3}(\.\d{1,2})?$. |
paymentLines[].tolerance.upAmount |
string, nullable | yes | Pattern: ^-?\d+(\.\d{1,2})?$. |
paymentLines[].tolerance.downAmount |
string, nullable | yes | Pattern: ^-?\d+(\.\d{1,2})?$. |
conditions |
object | yes | Approval of the matching conditions in fineelik. Every change of a condition (also one from ELO: partner, term, currency, payments) needs a new approval in fineelik. |
conditions.approved |
boolean | yes | |
conditions.pending |
boolean | yes | |
conditions.everApproved |
boolean | yes | |
conditions.approvedAt |
string (date-time), nullable | yes | |
conditions.fingerprint |
string | yes | |
conditions.approvedFingerprint |
string, nullable | yes | |
automationReady |
boolean | yes | See the description of the schema. |
automationBlockers |
array of string | yes | Reasons at the contract against the automatic approval: elo_not_active, conditions_not_approved, conditions_pending, auto_approve_off, company_auto_approve_off, partner_unassigned. Treat unknown codes as a reason against. |
openPoints |
array of string | yes | Open points for people: partner_unassigned, type_unknown (mask without contract type), conditions_not_approved, payments_incomplete (a payment without amount or cycle), quota_reached (the contract quota of the instance is reached and this contract does not take up a place yet, so its conditions cannot be submitted). |
AgreementEloHandover
Section titled “AgreementEloHandover”Hand over of a contract from ELO Contract. Field names and list keys as in ELO; unknown fields of an aspect are stored without loss. Money as decimal strings with at most two decimals.
| Field | Type | Required | Description |
|---|---|---|---|
companyId |
string (uuid) | no | Company in fineelik. A key is bound to one company; then leave it out (another value answers 404). |
revision |
string | yes | Revision of the contract in ELO, for example Sord.tStamp. Kept in the history. Up to 200 characters. |
changedAt |
string (date-time) | yes | Time of the change in ELO. A state older than the stored one is not applied (outcome stale). |
maskKey |
string | yes | Mask of the contract in ELO (GENERAL_CONTRACT, PARTNER_CONTRACT, SERVICE_CONTRACT, LEASE_CONTRACT, SALES_CONTRACT or a mask of the customer). It selects the contract type in fineelik; an unknown mask falls back to GENERAL_CONTRACT and is reported. Up to 64 characters. |
name |
string | yes | Short name of the contract (Sord.name), the title in fineelik. Up to 300 characters. |
CONTRACT_DETAILS |
object | yes | Aspect ELO_CONTRACT.CONTRACT_DETAILS with the ELO field names. CONTRACT_STATUS is required. Fields of type USER are objects with email (fineelik maps the person by e-mail) and name. |
CONTRACT_DETAILS.CONTRACT_STATUS |
string | yes | Up to 100 characters. |
CONTRACT_DETAILS.CONTRACT_NO |
string, nullable | no | Up to 100 characters. |
CONTRACT_DETAILS.CONTRACT_EXTERNAL_NO |
string, nullable | no | Up to 100 characters. |
CONTRACT_DETAILS.CONTRACT_TYPE |
string, nullable | no | Up to 200 characters. |
CONTRACT_DETAILS.CONTRACT_TYPE_KEY |
string, nullable | no | Up to 100 characters. |
CONTRACT_DETAILS.CONTRACT_PHASE |
string, nullable | no | Up to 100 characters. |
CONTRACT_DETAILS.CURRENCY |
string, nullable | no | Up to 3 characters. |
CONTRACT_DETAILS.BUSINESS_RELATION |
string, nullable | no | Up to 100 characters. |
CONTRACT_DETAILS.CONTRACT_RISK |
string, nullable | no | Up to 100 characters. |
CONTRACT_DETAILS.CONTRACT_DEPARTMENT |
string, nullable | no | Up to 200 characters. |
CONTRACT_DETAILS.DESCRIPTION |
string, nullable | no | Up to 10000 characters. |
CONTRACT_DETAILS.CONTRACT_RELATION |
string, nullable | no | Up to 100 characters. |
CONTRACT_DETAILS.CONTRACT_RESPONSIBLE |
object, nullable | no | |
CONTRACT_DETAILS.CONTRACT_RESPONSIBLE.name |
string, nullable | no | Up to 200 characters. |
CONTRACT_DETAILS.CONTRACT_RESPONSIBLE.email |
string (email), nullable | no | Up to 320 characters. |
CONTRACT_DETAILS.CONTRACT_PROCUREMENT |
object, nullable | no | |
CONTRACT_DETAILS.CONTRACT_PROCUREMENT.name |
string, nullable | no | Up to 200 characters. |
CONTRACT_DETAILS.CONTRACT_PROCUREMENT.email |
string (email), nullable | no | Up to 320 characters. |
CONTRACT_DETAILS.COUNTRY |
string, nullable | no | Up to 100 characters. |
CONTRACT_DETAILS.CONTRACT_APPLICABLE_LAW |
string, nullable | no | Up to 100 characters. |
CONTRACT_DETAILS.CONTRACT_PLACE_OF_EXECUTION |
string, nullable | no | Up to 100 characters. |
CONTRACT_DETAILS.CONTRACT_LANGUAGE |
string, nullable | no | Up to 100 characters. |
CONTRACT_DETAILS.ORGANIZATION |
string, nullable | no | Up to 200 characters. |
CONTRACT_PERIOD |
object, nullable | no | Aspect ELO_CONTRACT.CONTRACT_PERIOD with the ELO field names. |
CONTRACT_PERIOD.CONTRACT_START |
string (date), nullable | no | |
CONTRACT_PERIOD.CONTRACT_END |
string (date), nullable | no | |
CONTRACT_PERIOD.SIGNING_DATE |
string (date), nullable | no | |
CONTRACT_PERIOD.CONTRACT_DURATION |
integer, nullable | no | Minimum 0. Maximum 1200. |
CONTRACT_PERIOD.CONTRACT_DURATION_UNIT |
string, nullable | no | Up to 100 characters. |
CONTRACT_PERIOD.CONTRACT_DURATION_TYPE |
string, nullable | no | Up to 100 characters. |
CONTRACT_PERIOD.CONTRACT_EXTENSION_TYPE |
string, nullable | no | Up to 100 characters. |
CONTRACT_PERIOD.EXTENSION_BY_COUNT |
integer, nullable | no | Minimum 0. Maximum 1200. |
CONTRACT_PERIOD.EXTENSION_UNIT |
string, nullable | no | Up to 100 characters. |
CONTRACT_PERIOD.CONTRACT_END_AFTER_EXTENSION |
string (date), nullable | no | |
CONTRACT_PERIOD.ORIGINAL_CONTRACT_END |
string (date), nullable | no | |
CONTRACT_PERIOD.NEXT_CALC_DATE |
string (date), nullable | no | |
CONTRACT_PERIOD.CONTRACT_AUTO_CALCULATION |
integer, nullable | no | Minimum -9007199254740991. Maximum 9007199254740991. |
CONTRACT_TERMINATION |
object, nullable | no | Aspect ELO_CONTRACT.CONTRACT_TERMINATION with the ELO field names. |
CONTRACT_TERMINATION.TERMINATION_PERIOD |
integer, nullable | no | Minimum 0. Maximum 1200. |
CONTRACT_TERMINATION.TERMINATION_PERIOD_UNIT |
string, nullable | no | Up to 100 characters. |
CONTRACT_TERMINATION.TERMINATION_EFFECTIVE_FROM |
string, nullable | no | Up to 100 characters. |
CONTRACT_TERMINATION.TERMINATION_TYPE |
string, nullable | no | Up to 100 characters. |
CONTRACT_TERMINATION.DEADLINE_TYPE |
string, nullable | no | Up to 100 characters. |
CONTRACT_TERMINATION.TERMINATION_DAY_OF_MONTH |
integer, nullable | no | Minimum 1. Maximum 31. |
CONTRACT_TERMINATION.TERMINATION_MANUAL_END |
integer, nullable | no | Minimum -9007199254740991. Maximum 9007199254740991. |
CONTRACT_TERMINATION.TERMINATION_LAST_DATE |
string (date), nullable | no | |
CONTRACT_TERMINATION.POSSIBLE_EFFECTIVE_DATE |
string (date), nullable | no | |
CONTRACT_TERMINATION.TERMINATION_DATE |
string (date), nullable | no | |
CONTRACT_TERMINATION.TERMINATION_EFFECTIVE_DATE |
string (date), nullable | no | |
CONTRACT_TERMINATION.TERMINATION_CONTRACT_TYPE |
string, nullable | no | Up to 100 characters. |
CONTRACT_TERMINATION.TERMINATION_REASON |
string, nullable | no | Up to 2000 characters. |
CONTRACT_TERMINATION.TERMINATION_BY |
object, nullable | no | |
CONTRACT_TERMINATION.TERMINATION_BY.name |
string, nullable | no | Up to 200 characters. |
CONTRACT_TERMINATION.TERMINATION_BY.email |
string (email), nullable | no | Up to 320 characters. |
CONTRACT_TERMINATION.EXTRAORDINARY_PERIOD |
integer, nullable | no | Minimum 0. Maximum 1200. |
CONTRACT_TERMINATION.EXTRAORDINARY_PERIOD_UNIT |
string, nullable | no | Up to 100 characters. |
CONTRACT_TERMINATION.EXTRAORDINARY_EFFECTIVE_FROM |
string, nullable | no | Up to 100 characters. |
CONTRACT_TERMINATION.EXTRAORDINARY_CONDITION |
string, nullable | no | Up to 2000 characters. |
CONTRACT_TERMINATION.EXTRAORDINARY_LAST_DATE |
string (date), nullable | no | |
CONTRACT_TERMINATION.EXTRAORDINARY_EFFECTIVE_DATE |
string (date), nullable | no | |
CONTRACT_VALUE |
object, nullable | no | Aspect ELO_CONTRACT.CONTRACT_VALUE with the ELO field names. |
CONTRACT_VALUE.CURRENCY |
string, nullable | no | Up to 3 characters. |
CONTRACT_VALUE.CONTRACT_VALUE |
string, nullable | no | Pattern: ^-?\d+(\.\d{1,2})?$. |
CONTRACT_VALUE.SUM_PERIODIC_PAYMENTS |
string, nullable | no | Pattern: ^-?\d+(\.\d{1,2})?$. |
CONTRACT_VALUE.CONTRACT_END |
string (date), nullable | no | |
CONTRACT_STATUS_INFO |
object, nullable | no | Aspect ELO_CONTRACT.CONTRACT_STATUS_INFO. Stored, not evaluated. |
CONTRACT_STATUS_INFO.MESSAGE |
string, nullable | no | Up to 2000 characters. |
CONTRACT_STATUS_INFO.SENDER |
object, nullable | no | |
CONTRACT_STATUS_INFO.SENDER.name |
string, nullable | no | Up to 200 characters. |
CONTRACT_STATUS_INFO.SENDER.email |
string (email), nullable | no | Up to 320 characters. |
PARTNER |
array of object | no | Aspect ELO_CONTRACT.PARTNER, 0 to n entries. The first one is the contract partner. PARTNER is the GUID of the contact in ELO and the key of the remembered assignment to a vendor. Send name, vatId, taxNumber, creditorNumber and ibans of the contact when you have them: fineelik assigns the vendor automatically by the remembered assignment, the creditor number, the VAT or tax number, the IBAN and last the exact name, and never guesses between several hits. Default: []. |
PARTNER[].PARTNER |
string | yes | Up to 200 characters. |
PARTNER[].CONTACT_PERSON |
string, nullable | no | Up to 200 characters. |
PARTNER[].name |
string, nullable | no | Up to 300 characters. |
PARTNER[].vatId |
string, nullable | no | Up to 40 characters. |
PARTNER[].taxNumber |
string, nullable | no | Up to 40 characters. |
PARTNER[].creditorNumber |
string, nullable | no | Up to 60 characters. |
PARTNER[].ibans |
array of string | no | Default: []. |
PAYMENTS |
array of object | no | Aspect ELO_CONTRACT.PAYMENTS, 0 to n entries (CYCLE from ELO_COMMON.TIME_INTERVAL, SINGLE_AMOUNT as a decimal string). Send a stable lineKey per line when you have one, otherwise fineelik keys the lines by position. With DATE_TYPE RELATIVE send the resolved PAYMENT_START and PAYMENT_END. A line without amount or cycle is stored but not matched (warning payment_incomplete). Default: []. |
PAYMENTS[].lineKey |
string, nullable | no | Up to 100 characters. |
PAYMENTS[].PAYMENT_DESCRIPTION |
string, nullable | no | Up to 300 characters. |
PAYMENTS[].CYCLE |
string, nullable | no | Up to 100 characters. |
PAYMENTS[].SINGLE_AMOUNT |
string, nullable | no | Pattern: ^-?\d+(\.\d{1,2})?$. |
PAYMENTS[].PAYMENT_START |
string (date), nullable | no | |
PAYMENTS[].PAYMENT_END |
string (date), nullable | no | |
PAYMENTS[].PAYMENT_SUM |
string, nullable | no | Pattern: ^-?\d+(\.\d{1,2})?$. |
PAYMENTS[].PAYMENT_COUNT |
integer, nullable | no | Minimum 0. Maximum 9007199254740991. |
PAYMENTS[].DATE_TYPE |
string, nullable | no | Up to 100 characters. |
PAYMENTS[].REFERENCE_START_KEY |
string, nullable | no | Up to 100 characters. |
PAYMENTS[].REFERENCE_END_KEY |
string, nullable | no | Up to 100 characters. |
AgreementEloHandoverResponse
Section titled “AgreementEloHandoverResponse”| Field | Type | Required | Description |
|---|---|---|---|
outcome |
string | yes | created, updated, unchanged (the same payload as last time: nothing changed, nothing triggered) or stale (older than the stored state: nothing changed). One of: created, updated, unchanged, stale. |
conditionsChanged |
boolean | yes | true when the matching conditions changed: the automatic approval rests until the conditions are approved again in fineelik. |
approvalWithdrawn |
boolean | yes | true when a running approval of the conditions in fineelik was withdrawn because the conditions changed. It has to be submitted again. |
warnings |
array of object | yes | What was accepted but could not be mapped completely: unknown_value, payment_incomplete, currency_conflict, type_unknown, extra_partners, partner_unassigned, user_unmatched, each with the ELO field and value. |
warnings[].code |
string | yes | One of: unknown_value, payment_incomplete, currency_conflict, type_unknown, extra_partners, partner_unassigned, user_unmatched. |
warnings[].field |
string, nullable | yes | |
warnings[].value |
string, nullable | yes | |
state |
AgreementEloState | yes |
AgreementEloDocumentResponse
Section titled “AgreementEloDocumentResponse”| Field | Type | Required | Description |
|---|---|---|---|
agreementId |
string (uuid) | yes | |
documentId |
string (uuid) | yes | |
created |
boolean | yes |
InvoiceByDmsGuid
Section titled “InvoiceByDmsGuid”| Field | Type | Required | Description |
|---|---|---|---|
invoiceId |
string (uuid) | yes | Id of the invoice in fineelik. |
status |
string | yes | Status of the invoice. See “Invoice status” in the API introduction. 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. |
DmsTransferNextRequest
Section titled “DmsTransferNextRequest”| Field | Type | Required | Description |
|---|---|---|---|
invoiceId |
string (uuid) | no |
DmsTransferItem
Section titled “DmsTransferItem”| Field | Type | Required | Description |
|---|---|---|---|
invoiceId |
string (uuid) | yes | Id of the invoice in fineelik. Fetch the file with getInvoicePdf. |
companyId |
string (uuid) | yes | Company of the invoice. |
companyCode |
string | yes | Code of the company. |
fileName |
string | yes | Original file name, for the name of the document in the document management system. |
contentType |
string | yes | application/pdf, or application/xml for an e-invoice. |
byteSize |
integer, nullable | yes | Size of the file in bytes, if known. Minimum 0. Maximum 9007199254740991. |
captureChannel |
string | yes | How the document arrived in fineelik: upload (web app and mobile app), email (mailbox address) or api. One of: upload, email, api. |
createdAt |
string (date-time) | yes | When the document arrived in fineelik. |
attempt |
integer | yes | Which fetch of this document this is (1 = first). Minimum 0. Maximum 9007199254740991. |
DmsTransferNextResponse
Section titled “DmsTransferNextResponse”| Field | Type | Required | Description |
|---|---|---|---|
item |
object, nullable | yes | The next document for the document management system, or null if none is due. |
item.invoiceId |
string (uuid) | yes | |
item.companyId |
string (uuid) | yes | |
item.companyCode |
string | yes | |
item.fileName |
string | yes | |
item.contentType |
string | yes | |
item.byteSize |
integer, nullable | yes | Minimum 0. Maximum 9007199254740991. |
item.captureChannel |
string | yes | One of: upload, email, api. |
item.createdAt |
string (date-time) | yes | |
item.attempt |
integer | yes | Minimum 0. Maximum 9007199254740991. |
DmsTransferReportRequest
Section titled “DmsTransferReportRequest”Type: any of object, object
DmsTransferReportResponse
Section titled “DmsTransferReportResponse”| Field | Type | Required | Description |
|---|---|---|---|
invoiceId |
string (uuid) | yes | Id of the invoice. |
result |
string | yes | created (GUID set), repeated (the same GUID was already set), other_document (the invoice already belongs to another document, the reported one is a copy) or failed (reason stored, fineelik offers the document again later). One of: created, repeated, other_document, failed. |
status |
string | yes | Status of the invoice. See “Invoice status” in the API introduction. 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. |
InvoiceExport
Section titled “InvoiceExport”Neutral export state of one invoice for the leading system. It contains no field names or ids of a specific system; mapping to the target system is the job of the receiver.
Payment method. paymentMethod is null when none is set. erpCode is the payment form code in the ERP (Business Central Payment_Method_Code, Code[10]), stored on 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. In these cases the ERP keeps the payment form of the vendor, and the default of the company overwrites nothing that the ERP keeps differently. The receiver writes only codes and never clears an existing value.
Collective vendors. A collective vendor (a catch-all account such as “Various vendors EU”) is an ordinary vendor account in the leading system. In fineelik it holds one-time vendors as sub-vendors. Their name, VAT id, address, e-mail and bank details live only in fineelik. The export always names the collective vendor under vendor, because only that one is known to the leading system. There is no block for the sub-vendor.
Booking lines and document positions. lines are the booking lines as fineelik codes them (working state after template and review). One booking line can combine several positions of the document. documentLines are the positions as printed on the document: the unchangeable state of the extraction, in ascending order of position, including positions that belong to no booking line. lines[].documentPositions lists the position values of the document positions that a booking line combines (one each right after extraction). It is empty when the line does not come from a document position, for example when it was added in review. Documents without extracted positions (for example imported open items or invoices entered by hand) have documentLines: [] and documentPositions: [] in every line. The export always shows the current state: a new grouping in review changes only documentPositions; “process again” discards the document positions and reads them anew; reopening leaves them unchanged.
Service period and deferral. servicePeriodStart and servicePeriodEnd are the service period according to the document (YYYY-MM-DD or null). A single service date appears as from = 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. The deferral of a line with a deferral code (lines[].accounting.deferral_code) starts at servicePeriodStart; the number of periods comes from the template in the ERP.
| Field | Type | Required | Description |
|---|---|---|---|
invoiceId |
string (uuid) | yes | Id of the invoice. |
revision |
string | yes | Opaque fingerprint of the whole export. It changes with anything in the export, also with status, reason, review note (reviewedAt, reviewedBy), vendor and master data of the company. |
dataRevision |
string | yes | Opaque fingerprint of only those invoice data that the receiver writes into its own invoice: company.code, documentType, invoiceNumber, invoiceDate, deliveryDate, servicePeriodStart, servicePeriodEnd, dueDate, currency, netAmount, taxAmount, grossAmount, homeAmounts (when present), taxLines, paymentTerms, accounting (header), lines with their accounting (also deferral_code) and documentPositions, documentLines, the explicit vendor assignment vendor.id (or null) and paymentMethod.erpCode, only when it is set. NOT covered: the other vendor master data under vendor, company.id, company.name, company.vatId, invoiceId, dmsGuid, status, statusReason and the review note. Write invoice data only when dataRevision is new. Then a pure status change, renaming a vendor or linking it to the ERP for the first time overwrites no correction made in the leading system. Take the vendor account (vendor.erpVendorNumber) over separately, on invoice.export_changed and only where it is still missing. A change of the assigned vendor (A to B) changes dataRevision. |
dmsGuid |
string, nullable | yes | GUID of the document in the document management system, or null. |
status |
string | yes | Status of the invoice. See “Invoice status” in the API introduction. 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. |
statusReason |
string, nullable | yes | Reason for the status, for example approval_external. |
company |
object | yes | The company the invoice belongs to. |
company.id |
string (uuid) | yes | Id of the company. |
company.code |
string | yes | Code of the company. The receiver uses it to select its own unit. |
company.name |
string | yes | Name of the company. |
company.vatId |
string, nullable | yes | VAT id of the company, if known. |
vendor |
object, nullable | yes | The matched vendor, or null when none is assigned. For invoices of a sub-vendor this is the collective vendor. |
vendor.id |
string (uuid) | yes | Id of the vendor in fineelik. |
vendor.name |
string | yes | Name of the vendor. |
vendor.vatId |
string, nullable | yes | VAT id of the vendor, if known. |
vendor.countryCode |
string, nullable | yes | Country code of the vendor, if known. |
vendor.erpVendorNumber |
string, nullable | yes | Vendor account number in the ERP (Business Central “No.”), if linked. |
vendor.erpExternalId |
string, nullable | yes | Id in the ERP (Business Central SystemId), if linked. |
documentType |
string | yes | invoice or credit_note. One of: invoice, credit_note. |
invoiceNumber |
string, nullable | yes | Invoice number as printed on the document. |
invoiceDate |
string (date), nullable | yes | Invoice date. |
deliveryDate |
string (date), nullable | yes | Delivery date. |
servicePeriodStart |
string (date), nullable | yes | Start of the service period according to the document, or null. |
servicePeriodEnd |
string (date), nullable | yes | End of the service period according to the document, or null. |
dueDate |
string (date), nullable | yes | Due date. |
currency |
string, nullable | yes | Currency of the document (ISO 4217). Pattern: ^[A-Z]{3}$. |
netAmount |
string, nullable | yes | Net amount as a decimal string. Pattern: ^-?\d+(\.\d+)?$. |
taxAmount |
string, nullable | yes | Tax amount as a decimal string. Pattern: ^-?\d+(\.\d+)?$. |
grossAmount |
string, nullable | yes | Gross amount as a decimal string. Pattern: ^-?\d+(\.\d+)?$. |
homeAmounts |
object, nullable | yes | Amounts in the home currency of the company at the rate of the invoice date. null for invoices in the home currency and while no rate is available (for example the invoice date or gross amount is missing, the date lies in the future, or the currency has no ECB rate). |
homeAmounts.currency |
string | yes | Home currency of the company. Pattern: ^[A-Z]{3}$. |
homeAmounts.exchangeRate |
string | yes | Units of the invoice currency per one unit of the home currency, as quoted by the ECB. For 1 EUR = 1.0832 USD this is "1.0832". The home amount is the amount divided by the rate, rounded commercially to the decimals of the home currency. Pattern: ^-?\d+(\.\d+)?$. |
homeAmounts.rateDate |
string (date) | yes | Date of the rate. |
homeAmounts.source |
string | yes | ECB for a rate of the European Central Bank, fixed for a fixed rate. One of: ECB, fixed. |
homeAmounts.netAmount |
string, nullable | yes | Net amount in the home currency, or null. Pattern: ^-?\d+(\.\d+)?$. |
homeAmounts.grossAmount |
string | yes | Gross amount in the home currency. Pattern: ^-?\d+(\.\d+)?$. |
taxLines |
array of object | yes | Tax by tax rate. |
taxLines[].taxRate |
string | yes | Tax rate in percent. Pattern: ^-?\d+(\.\d+)?$. |
taxLines[].netAmount |
string | yes | Net amount for this rate. Pattern: ^-?\d+(\.\d+)?$. |
taxLines[].taxAmount |
string | yes | Tax amount for this rate. Pattern: ^-?\d+(\.\d+)?$. |
paymentTerms |
array of object | yes | Payment terms of the invoice. |
paymentTerms[].rank |
integer | yes | 1 is the term that fineelik applies (the best valid one). Minimum -9007199254740991. Maximum 9007199254740991. |
paymentTerms[].dueDate |
string (date), nullable | yes | Due date of this term, or null. |
paymentTerms[].days |
integer, nullable | yes | Number of days of this term, or null. Minimum -9007199254740991. Maximum 9007199254740991. |
paymentTerms[].discountPercent |
string, nullable | yes | Cash discount in percent, or null. Pattern: ^-?\d+(\.\d+)?$. |
paymentTerms[].discountAmount |
string, nullable | yes | Cash discount amount, or null. Pattern: ^-?\d+(\.\d+)?$. |
paymentMethod |
object, nullable | yes | Payment method of the invoice, or null when none is set. See the notes of this schema. |
paymentMethod.kind |
string | yes | Kind of payment method: bank_transfer, direct_debit, credit_card, debit_card, online or cash. One of: cash, credit_card, bank_transfer, private_outlay, direct_debit, debit_card, online. |
paymentMethod.label |
string | yes | Name of the payment method. |
paymentMethod.erpCode |
string, nullable | yes | Payment form code in the ERP (for example Business Central Payment_Method_Code), or null. See the notes of this schema. |
paymentMethod.source |
string, nullable | yes | Where the payment method comes from: extraction, vendor_default, company_default, manual or null. One of: extraction, vendor_default, company_default, manual. |
accounting |
object | yes | Account coding on header level (for example the business posting groups) as dimensions. The key comes from the field catalog of the ERP adapter, the value holds code and label. |
lines |
array of object | yes | Booking lines with their account coding. See the notes of this schema for how they relate to documentLines. |
lines[].lineNumber |
integer | yes | Number of the booking line. Minimum -9007199254740991. Maximum 9007199254740991. |
lines[].documentPositions |
array of integer | yes | The position values of the document positions that this booking line combines. Empty when the line does not come from a document position. |
lines[].description |
string | yes | Description of the line. |
lines[].quantity |
string, nullable | yes | Quantity as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$. |
lines[].unit |
string, nullable | yes | Code of a unit of the company (master data type unitsOfMeasure), or null when no unit is assigned. With Business Central it is the Business Central code (Code[10]). Without an ERP the standard units carry UN/ECE codes (Recommendation 20, package and unit from Recommendation 21 with a leading X), for example H87 piece, HUR hour, LS lump sum, KGM kilogram; units created by hand keep their own code. The unit as printed is in documentLines[].unit. Documents from before the switch of 28 September 2026 can still carry the printed text here until someone picks the unit in review. |
lines[].unitPrice |
string, nullable | yes | Unit price as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$. |
lines[].netAmount |
string, nullable | yes | Net amount as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$. |
lines[].taxRate |
string, nullable | yes | Tax rate in percent as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$. |
lines[].taxAmount |
string, nullable | yes | Tax amount as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$. |
lines[].grossAmount |
string, nullable | yes | Gross amount as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$. |
lines[].accounting |
object | yes | Account coding of the line as dimensions. The key comes from the field catalog of the ERP adapter (for example general_ledger_account, cost_center, cost_bearer, general_product_posting_group, vat_product_posting_group, general_business_posting_group, vat_business_posting_group, booking_text, deferral_code and further dimensions), the value holds code and label. Lines without deferral have no deferral_code key. |
documentLines |
array of object | yes | The positions as printed on the document (unchangeable state of the extraction), in ascending order of position. |
documentLines[].position |
integer | yes | Position on the document. Minimum -9007199254740991. Maximum 9007199254740991. |
documentLines[].description |
string | yes | Description as printed. |
documentLines[].quantity |
string, nullable | yes | Quantity as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$. |
documentLines[].unit |
string, nullable | yes | Unit as printed. This is text, not a code. |
documentLines[].unitPrice |
string, nullable | yes | Unit price in full precision as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$. |
documentLines[].netAmount |
string, nullable | yes | Net amount with two decimals as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$. |
documentLines[].taxRate |
string, nullable | yes | Tax rate with two decimals as a decimal string, or null. Pattern: ^-?\d+(\.\d+)?$. |
reviewedAt |
string (date-time), nullable | yes | When accounting finished the review in fineelik, or null. |
reviewedBy |
string, nullable | yes | Who finished the review in fineelik, or null. |
agreementMatch |
object, nullable | yes | Contract block (module “Contracts”). null without the module or when the invoice is not assigned to a contract. It carries the result of the contract check, one entry per effective assignment and whether fineelik would approve the invoice automatically (autoApprovalPossible) with the reasons against it (blockers), by the same rules as the automatic approval inside fineelik, without changing anything. A leading system that approves on its own (for example ELO) can skip its approval step when autoApprovalPossible is true. Confidential contracts: a machine is never a named viewer. For a confidential contract the entry holds only confidential and result; number, external number and all amounts of the contract are null. Default: null. |
agreementMatch.outcome |
string | yes | Result for the whole invoice: ok (fully assigned, within the tolerance, nothing open), deviation, unchecked (an assignment could not be checked, for example without amount), suggested (only a suggestion, or an open suggestion beside the assignment), partial (not every position is assigned, or positions are assigned twice) or none. One of: ok, deviation, unchecked, suggested, partial, none. |
agreementMatch.autoApprovalPossible |
boolean | yes | true when every rule of the automatic approval holds, so blockers is empty. |
agreementMatch.blockers |
array of string | yes | Reasons against the automatic approval, as codes in a fixed order: module_not_licensed, company_auto_approve_off, match_failed, outcome_none, outcome_suggested, outcome_partial, outcome_unchecked, outcome_deviation, agreement_not_active, conditions_not_approved, conditions_pending, agreement_auto_approve_off, vendor_mismatch, amount_missing, max_amount_exceeded, first_invoice_of_vendor, bank_account_deviates, bank_account_recently_changed, duplicate_suspected, open_error_findings, credit_note, currency_mismatch, second_invoice_in_period, needs_clearance, order_match_deviation, sample_due. Treat unknown codes as a reason against. |
agreementMatch.links |
array of object | yes | One entry per effective assignment (automatic, manual or confirmed). |
agreementMatch.links[].confidential |
boolean | yes | true for a confidential contract. Then every field except result is null. |
agreementMatch.links[].agreementId |
string (uuid), nullable | yes | Id of the contract in fineelik. |
agreementMatch.links[].number |
string, nullable | yes | Number of the contract in fineelik. |
agreementMatch.links[].externalNumber |
string, nullable | yes | Number of the contract at the partner or in the leading system, or null. |
agreementMatch.links[].matchSource |
string, nullable | yes | auto, suggested (confirmed by a person) or manual. One of: auto, suggested, manual. |
agreementMatch.links[].result |
string | yes | Result of the check: ok, deviation or unchecked. One of: ok, deviation, unchecked. |
agreementMatch.links[].currency |
string, nullable | yes | Currency of the contract (ISO 4217). |
agreementMatch.links[].expectedAmount |
string, nullable | yes | Expected amount for the period of the invoice (net or gross as set in the contract). Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].actualAmount |
string, nullable | yes | Actual amount of the invoice or of its assigned positions. Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].deviationAmount |
string, nullable | yes | Actual minus expected amount (positive above the expected amount). Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].deviationPercent |
string, nullable | yes | Deviation in percent of the expected amount, two decimals. |
agreementMatch.links[].allowedUpAmount |
string, nullable | yes | Allowed deviation upwards as an amount. Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].allowedDownAmount |
string, nullable | yes | Allowed deviation downwards as an amount. Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].externalGuid |
string, nullable | yes | Default: null. |
Webhook
Section titled “Webhook”| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | yes | Id of the webhook. |
url |
string | yes | Target address. Values of query parameters and a fragment are masked as ***. |
urlHasSecret |
boolean | yes | true when the address contains hidden values (query parameters or a fragment). To change the address, enter it completely again. |
description |
string, nullable | yes | Free text, up to 200 characters. |
eventTypes |
array of string | yes | The event types that are delivered. |
companyId |
string (uuid), nullable | yes | The company the webhook is limited to. null means all companies the creator can see. |
companyName |
string, nullable | yes | Name of that company, or null. |
active |
boolean | yes | false while the webhook is paused. |
createdAt |
string (date-time) | yes | When the webhook was created. |
cursor |
string | yes | Number of the last event up to which everything that matches was delivered. Pattern: ^\d{1,19}$. |
pendingEvents |
integer | yes | Number of events that still wait for delivery (with the current access of the creator). Minimum 0. Maximum 9007199254740991. |
lastDeliveryAt |
string (date-time), nullable | yes | Time of the last delivery attempt, or null. |
lastDeliveryOk |
boolean, nullable | yes | Whether the last attempt succeeded, or null. |
lastError |
string, nullable | yes | Error of the last failed attempt (the address is masked), or null. webhook.creator_no_access when the creator has no access any more. |
failingSince |
string (date-time), nullable | yes | Since when deliveries fail, or null while they work. |
WebhookList
Section titled “WebhookList”| Field | Type | Required | Description |
|---|---|---|---|
items |
array of Webhook | yes | The webhooks. |
CreateWebhookRequest
Section titled “CreateWebhookRequest”| Field | Type | Required | Description |
|---|---|---|---|
url |
string (uri) | yes | Target address. https only, no credentials in the address, up to 500 characters. A token in the query part is allowed (ELO Flows) and appears only masked in answers. Up to 500 characters. |
description |
string, nullable | no | Free text, up to 200 characters. Up to 200 characters. |
eventTypes |
array of string | yes | At least one of invoice.received, invoice.status_changed, invoice.export_changed, invoice.processing_failed. |
companyId |
string (uuid), nullable | no | Limit the webhook to one company (it must be within your access). Without it, all companies you can see at this moment. |
secret |
string | no | Optional own secret (24 to 200 characters), for example the one entered in ELO Flows. Without it, fineelik generates one. Up to 200 characters. |
CreateWebhookResponse
Section titled “CreateWebhookResponse”| Field | Type | Required | Description |
|---|---|---|---|
subscription |
Webhook | yes | |
secret |
string | yes | The signing secret. It appears only in this answer and in the answer to renewing, and never again. |
UpdateWebhookRequest
Section titled “UpdateWebhookRequest”Fields to change. At least one field is required.
| Field | Type | Required | Description |
|---|---|---|---|
url |
string (uri) | no | New target address, always complete. An address that contains *** is refused with 400 webhook.url_masked. Up to 500 characters. |
description |
string, nullable | no | Free text, up to 200 characters. null clears it. Up to 200 characters. |
eventTypes |
array of string | no | The event types to deliver, at least one. |
companyId |
string (uuid), nullable | no | Limit to one company, or null for all companies you can see. |
active |
boolean | no | false pauses the webhook, true resumes it. |
RotateWebhookSecretRequest
Section titled “RotateWebhookSecretRequest”| Field | Type | Required | Description |
|---|---|---|---|
secret |
string | no | Optional own secret (24 to 200 characters). Without it, fineelik generates a new one. Up to 200 characters. |
RotateWebhookSecretResponse
Section titled “RotateWebhookSecretResponse”| Field | Type | Required | Description |
|---|---|---|---|
secret |
string | yes | The new signing secret. It appears only in this answer. The old one is invalid now. |
WebhookTestResult
Section titled “WebhookTestResult”| Field | Type | Required | Description |
|---|---|---|---|
ok |
boolean | yes | true when the target answered with a 2xx status. |
statusCode |
integer, nullable | yes | HTTP status of the answer, or null when there was none. Minimum -9007199254740991. Maximum 9007199254740991. |
error |
string, nullable | yes | Error text (the address is masked), or null. |
durationMs |
integer | yes | Duration of the call in milliseconds. Minimum 0. Maximum 9007199254740991. |
WebhookDelivery
Section titled “WebhookDelivery”One delivery attempt in the log.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string (uuid) | yes | Id of the delivery attempt. The same value is sent in the header X-Fineelik-Delivery. |
eventId |
string, nullable | yes | Number of the event, or null for a test call. Pattern: ^\d{1,19}$. |
eventType |
string | yes | Type of the event (ping for a test call). |
invoiceId |
string (uuid), nullable | yes | Id of the invoice, or null for a test call. |
attemptedAt |
string (date-time) | yes | When the attempt was made. |
statusCode |
integer, nullable | yes | HTTP status of the answer, or null when there was none. Minimum -9007199254740991. Maximum 9007199254740991. |
ok |
boolean | yes | true when the target answered with a 2xx status. |
error |
string, nullable | yes | Error text (the address is masked), or null. |
durationMs |
integer | yes | Duration of the call in milliseconds. Minimum 0. Maximum 9007199254740991. |
WebhookDeliveries
Section titled “WebhookDeliveries”| Field | Type | Required | Description |
|---|---|---|---|
items |
array of WebhookDelivery | yes | Delivery attempts, newest first. |
total |
integer | yes | Number of all entries, for paging. Minimum 0. Maximum 9007199254740991. |
WebhookEvent
Section titled “WebhookEvent”The JSON body of a webhook delivery. It has the same shape as one entry of listIntegrationEvents. The only addition is the type ping, which appears in test calls (testWebhook) and means nothing: acknowledge unknown types with 2xx and ignore them.
A test call uses type ping, id "0", the invoice id 00000000-0000-0000-0000-000000000000 and the company of the webhook (the same zero UUID without a fixed company). It changes neither the cursor nor the failure count and appears in the delivery log.
Headers of the delivery
X-Fineelik-Signature:t=<unix seconds>,v1=<hex>(signature with a timestamp, recommended).X-Hub-Signature:sha256=<hex>(WebSub format, checked by ELO Flows itself).X-Fineelik-Event: the event type (pingfor a test call).X-Fineelik-Delivery: id of this delivery attempt (it appears in the delivery log).User-Agent:fineelik-webhooks/1.Content-Type:application/json.
Verifying the signature. fineelik sends both signatures with the same secret; check one of them. The key is the secret exactly as shown or given, including whsec_ if present (UTF-8). body is the raw request body, byte for byte and before any JSON parsing. Compare in constant time.
X-Fineelik-Signature:v1is the hex HMAC-SHA256 of<t>.<body>, wheretis the value from the header. Reject timestamps that are more than 5 minutes away from your own clock. This guards against replay.X-Hub-Signature:sha256=followed by the hex HMAC-SHA256 of<body>, without a timestamp. Against replay use the event numberid, which a receiver evaluates for “at least once” anyway.
Test vector: secret whsec_testgeheimnis, t = 1700000000 and body {"id":"42","type":"invoice.status_changed"} give v1=d5f4a33b0c6510fdb99e15e5aa059c51cea8869e2fe7407b161a3e4c1d58f7df and X-Hub-Signature: sha256=21e78171381c266463b9c9ad85f8d0a92d55f7480ce503feb72ed982db8239c4.
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | yes | Sequence number of the event, as a string. Unique and ascending. Use it as the cursor for the next call and to recognize an event that arrives twice. Pattern: ^\d{1,19}$. |
type |
string | yes | Kind of event, see IntegrationEvent. ping appears only in test calls and carries no data. Events about contracts managed in ELO (agreement.*) arrive in the form AgreementIntegrationEvent. Acknowledge and ignore unknown types. One of: invoice.received, invoice.status_changed, invoice.export_changed, invoice.processing_failed, ping. |
occurredAt |
string (date-time) | yes | When the event was created. |
invoiceId |
string (uuid) | yes | Id of the invoice. |
companyId |
string (uuid) | yes | Id of the company of the invoice. |
companyCode |
string | yes | Code of the company. |
dmsGuid |
string, nullable | yes | GUID of the document in the document management system (for example ELO) when the invoice came from there, otherwise null. |
status |
string | yes | Status of the invoice after the event. 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. |
previousStatus |
string, nullable | yes | Only for invoice.status_changed: the status before. Otherwise null. 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. |
statusReason |
string, nullable | yes | Reason for the status after the event, if any. |
agreementMatch |
object, nullable | yes | Contract block (module “Contracts”) as it is when the event is fetched or delivered, the same as agreementMatch in InvoiceExport. null without the module, without assignment, or when it could not be determined (then do not approve automatically). Confidential contracts: only confidential and result per entry, no number and no amounts. Default: null. |
agreementMatch.outcome |
string | yes | Result for the whole invoice: ok (fully assigned, within the tolerance, nothing open), deviation, unchecked (an assignment could not be checked, for example without amount), suggested (only a suggestion, or an open suggestion beside the assignment), partial (not every position is assigned, or positions are assigned twice) or none. One of: ok, deviation, unchecked, suggested, partial, none. |
agreementMatch.autoApprovalPossible |
boolean | yes | true when every rule of the automatic approval holds, so blockers is empty. |
agreementMatch.blockers |
array of string | yes | Reasons against the automatic approval, as codes in a fixed order: module_not_licensed, company_auto_approve_off, match_failed, outcome_none, outcome_suggested, outcome_partial, outcome_unchecked, outcome_deviation, agreement_not_active, conditions_not_approved, conditions_pending, agreement_auto_approve_off, vendor_mismatch, amount_missing, max_amount_exceeded, first_invoice_of_vendor, bank_account_deviates, bank_account_recently_changed, duplicate_suspected, open_error_findings, credit_note, currency_mismatch, second_invoice_in_period, needs_clearance, order_match_deviation, sample_due. Treat unknown codes as a reason against. |
agreementMatch.links |
array of object | yes | One entry per effective assignment (automatic, manual or confirmed). |
agreementMatch.links[].confidential |
boolean | yes | true for a confidential contract. Then every field except result is null. |
agreementMatch.links[].agreementId |
string (uuid), nullable | yes | Id of the contract in fineelik. |
agreementMatch.links[].number |
string, nullable | yes | Number of the contract in fineelik. |
agreementMatch.links[].externalNumber |
string, nullable | yes | Number of the contract at the partner or in the leading system, or null. |
agreementMatch.links[].matchSource |
string, nullable | yes | auto, suggested (confirmed by a person) or manual. One of: auto, suggested, manual. |
agreementMatch.links[].result |
string | yes | Result of the check: ok, deviation or unchecked. One of: ok, deviation, unchecked. |
agreementMatch.links[].currency |
string, nullable | yes | Currency of the contract (ISO 4217). |
agreementMatch.links[].expectedAmount |
string, nullable | yes | Expected amount for the period of the invoice (net or gross as set in the contract). Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].actualAmount |
string, nullable | yes | Actual amount of the invoice or of its assigned positions. Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].deviationAmount |
string, nullable | yes | Actual minus expected amount (positive above the expected amount). Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].deviationPercent |
string, nullable | yes | Deviation in percent of the expected amount, two decimals. |
agreementMatch.links[].allowedUpAmount |
string, nullable | yes | Allowed deviation upwards as an amount. Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].allowedDownAmount |
string, nullable | yes | Allowed deviation downwards as an amount. Pattern: ^-?\d+(\.\d{1,2})?$. |
agreementMatch.links[].externalGuid |
string, nullable | yes | Default: null. |