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.
Handover
Section titled “Handover”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) orstale(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 exampleunknown_value,payment_incomplete,type_unknown,partner_unassignedoruser_unmatched, each with the ELO field path infield.
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).
Document
Section titled “Document”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.
State and events
Section titled “State and events”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 invoice data
Section titled “In the invoice data”- 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-decisioncounts for the sample of the automatic approval (“every n-th”) exactly once per invoice, see External approval.