Skip to content

Contracts from ELO

With the Contracts module (agreements) a contract that is managed in ELO Contract stays leading in ELO. The ELO component hands it over to fineelik, fineelik matches invoices against it and keeps what ELO Contract does not know (net or gross, tolerances, automatic approval, vendor, object numbers, tags). The way back is the agreement events and the state call.

Call Right Effect
PUT /api/integration/agreements/{externalGuid} agreements.integration_write create or update the contract from ELO
POST /api/integration/agreements/{externalGuid}/documents agreements.integration_write add the contract document (multipart, field file)
GET /api/integration/agreements/{externalGuid} agreements.integration_read the state of the contract with the fields fineelik keeps

externalGuid is the GUID of the contract in ELO (Sord.guid, with or without braces). Both rights belong only to the Administrator role, so the key must belong to an administrator. A key sees only its own company: a contract of another company answers 404 like an unknown one.

The body follows the ELO model one to one: the aspects keep their ELO names (CONTRACT_DETAILS, CONTRACT_PERIOD, CONTRACT_TERMINATION, CONTRACT_VALUE, CONTRACT_STATUS_INFO, PARTNER, PAYMENTS), their fields the ELO field names and list values the ELO keys. Next to them:

Field Required Meaning
companyId no the company; a key bound to a company may leave it out
revision yes the state in ELO (for example Sord.tStamp), shown in the history
changedAt yes time of the change in ELO (ISO 8601 with offset); an older state than the stored one is ignored
maskKey yes the mask of the contract in ELO; unknown masks become a general contract
name yes the short name in ELO, the title in fineelik

CONTRACT_DETAILS.CONTRACT_STATUS is required (DRAFT up to ENDED, COMPLETED means active). Money is a decimal string with at most two decimals, dates are YYYY-MM-DD. Each payment may carry a lineKey, the stable ID of the line in ELO; without it fineelik matches lines by position. Through this key the details fineelik keeps per payment (kind, object number, tolerance) stay when the contract changes. A payment that is missing in a later handover is marked as removed, never deleted. Each partner carries PARTNER (the GUID of the contact in ELO) and, if known, name, vatId, taxNumber, creditorNumber and ibans: fineelik maps the partner to a vendor with them and never guesses.

The answer (200) is { outcome, conditionsChanged, approvalWithdrawn, warnings, state }:

  • outcome: created, updated, unchanged (the same body as last time, nothing changed and nothing was triggered) or stale (older than the stored state, nothing changed).
  • conditionsChanged: the matching conditions changed. The contract must be approved again in fineelik before invoices are approved automatically again, and the responsible persons get a notice.
  • approvalWithdrawn: a running approval of the conditions was withdrawn.
  • warnings: accepted, but not everything could be used, for example unknown_value, payment_incomplete, type_unknown, partner_unassigned or user_unmatched, each with the ELO field path in field.

Errors: 422 agreement_elo.unknown_status (unknown CONTRACT_STATUS), 422 agreement_elo.company_required (no company), 409 agreement_elo.company_mismatch (the GUID belongs to another company), 409 agreement_elo.not_elo_managed (the GUID belongs to a contract kept in fineelik).

POST /api/integration/agreements/{externalGuid}/documents takes the PDF in the multipart field file plus dmsGuid (the GUID of the document in ELO), optionally dmsVersion and role (main, amendment, termination or other, default main). The answer is { agreementId, documentId, created }. The same document (same dmsGuid and file hash) again answers created: false. Documents from ELO cannot be removed in fineelik.

GET /api/integration/agreements/{externalGuid} returns the state: status in fineelik and the ELO key (eloStatus), partner mapping, net or gross, tolerance, automatic approval, confirmed tags (tags, and tagsText joined with ; for a text field in ELO), match keys, responsible persons by e-mail, the payment lines with the fineelik details, the state of the conditions approval, automationReady with automationBlockers, and openPoints. It contains no content of documents and no title, also for confidential contracts.

The events agreement.conditions_approved, agreement.conditions_changed, agreement.partner_assigned, agreement.tags_changed and agreement.auto_approve_changed carry the same state in agreement, read when the event is fetched, see Events and export.

  • In the contract block of the export and the events, a link to a contract from ELO carries externalGuid, so that ELO can set the relation. Also for confidential contracts, because ELO knows the ID anyway.
  • If only the contract block of an invoice that was already reviewed changes (for example after a new match), fineelik writes invoice.export_changed.
  • With approval outside fineelik, the decision reported with POST /api/invoices/{id}/external-decision counts for the sample of the automatic approval (“every n-th”) exactly once per invoice, see External approval.