Cleaning and Key Rules

Work the cleaning list of contracts that look wrong, dismiss reviewed issues, merge contracts, reconcile renumbered ones and teach key rules.

Documents arrive under the keys the document store gives them, and a contract is sometimes split: a renumbered contract lives under two keys, a letter carries no number at all, one number covers several sites. The cleaning routes show where the documents disagree and give a person the tools to resolve it. Each route acts on contract keys, and the keys a person sets are hand-set, so they are kept when documents are read again.

The Cleaning Worklist

GET /v1/contracts/issues returns, per contract, the issues the documents show, each naming the documents it is about. Contracts with the most issues come first, and only contracts with at least one open issue appear. The issue codes are several_base_contracts, printed_number_differs, several_counterparties, several_sites, ended_by_message, unread_documents, no_dates, unverified_terms, no_own_party and direction_conflict.

{
  "data": [
    {
      "contract_id": "6f1c2a9e-1d4b-4a7e-9c33-2b8a5e0d7f11",
      "contract_key": "1043020-WLV",
      "title": "Waermelieferungsvertrag",
      "status": "active",
      "issues": [
        {
          "code": "ended_by_message",
          "detail": "an email or message is read as the termination; confirm it or leave it out",
          "document_ids": ["5e91a7d3-4c20-4b8f-9d16-3a7c0e2b8f54"]
        }
      ]
    }
  ]
}

POST /v1/contracts/{id}/issues/{code}/dismiss records that a reviewed issue is right as it stands, for example a genuine termination e-mail or a customer number printed on the contract. The note (3 to 2000 characters) says why. The dismissal is keyed on the contract, the code and the documents concerned, so an issue stays hidden until the documents concerned change: a further document that raises the same code flags it again. A code for which the contract has no open issue returns 404.

Merge and Reconcile

POST /v1/contracts/{id}/merge re-keys every document of the contract to into_key, which is created when no contract has it yet, and deletes the emptied contract. The merge is recorded as a key rule, so later documents filed under the old key go to the target key, and an open decision on the old contract carries over to the target when the target has none. The response is 201 with moved (the number of documents) and the resulting contract.

POST /v1/contracts/reconcile does the merging automatically where the evidence is clear. It merges a renumbered contract into the key it continues under when that contract exists, and it attaches a document that has no contract number anywhere (and is not a base contract) to the one contract whose base contract names the same counterparty, and the same site when the document names one. Documents a person filed by hand never move. With dry_run: true it reports the planned merge and attach moves and makes none.

curl -X POST "https://api.talonic.com/v1/contracts/reconcile" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'

Key Rules

A key rule files the documents of one contract key (optionally only at one site) under another key. GET /v1/contracts/key-rules lists the rules, ordered by from_key and then site; withdrawn rules are listed with active: false. POST /v1/contracts/key-rules adds a rule or replaces and re-activates the rule for the same from_key and site. DELETE /v1/contracts/key-rules/{ruleId} sets a rule inactive. In every case, documents already filed stay where they are until they are re-read or re-keyed.

curl -X POST "https://api.talonic.com/v1/contracts/key-rules" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from_key": "4243", "to_key": "1042430", "site": "Musterstadt Nord", "note": "Renumbered in 2024"}'