Understand Vexless

Parties

Customers, suppliers, banks, authorities. Vexless resolves them from the identifiers on the documents you send; you never create one.

Naming a party

Wherever a party is expected, the buyer on a sales invoice, the seller on a purchase invoice, the counterparty on a bank transaction, send any one identifier. Vexless resolves it to an existing party or creates one.

"buyer":        { "businessId": "7654321-1", "name": "Ostaja Oy", "externalId": "cust-42" }
"seller":       { "businessId": "1111111-1", "iban": "FI4250001510000023" }
"counterparty": { "name": "OSTAJA OY", "iban": "FI2112345600000785" }                         # as the bank reports it
"buyer":        { "partyId": "pty_…" }

A party with no identifier at all answers 400 PARTY_UNRESOLVED. A bank counterparty is usually a name and an IBAN, which is enough.

What you get back

Always your own company's view of the party: the name you gave, or the identifier you gave when you gave no name, your externalId, and only the identifiers your company supplied.

GET /v1/companies/{companyId}/parties?externalId=sup-88

{ "items": [ { "id": "prl_…", "partyId": "pty_…", "name": "Toimittaja Oy", "country": "FI", "roles": ["SUPPLIER"], "externalId": "sup-88",
               "defaultAccountNumber": "6000", "defaultTaxCode": "FI_PURCHASE_25_5",
               "identifiers": [ { "scheme": "BUSINESS_ID", "value": "1111111-1", "source": "DOCUMENT" },
                                { "scheme": "IBAN", "value": "FI4250001510000023", "source": "PARTNER" } ],
               "createdAt": "…" } ],
  "next": null }

partyId is the id you use on origins and in filters, and the paging cursor. roles accumulate from what the party has been to this company: CUSTOMER, SUPPLIER, BANK, AUTHORITY, EMPLOYEE. A party belongs to one company: if another company invoices the same supplier, that is a different party, and nothing you send here is visible to it.

Shared memory, private views

A party belongs to one company. Send the same business id under two companies and you get two parties, resolved and named independently; nothing one company supplies reaches the other. Within a company, any identifier you have sent before resolves to the party you already have, so repeat invoices from a supplier land on the same party without you sending its id again. Payments use only the IBANs your company supplied.

Your ids

externalId is your customer or supplier id, unique per company and partner. Set it on the first origin, or later with a party update, and it comes back on every origin's parties[], every open item as partyExternalId, and every event that names a party. Filter parties by it. It is the id your software joins on.

Updating a party

PATCH /v1/companies/{companyId}/parties/{partyId}
{ "name": "Our Supplier", "externalId": "sup-88", "iban": "FI4250001510000023" }   # origins:write
{ "defaultAccountNumber": "6000", "defaultTaxCode": "FI_PURCHASE_25_5" }            # accounts:manage

The response is the party as above. An IBAN you add here is one Vexless may pay to; it is stored with source PARTNER. externalId and the defaults accept null to clear.

Party defaults are hints

defaultAccountNumber and defaultTaxCode are a note about that supplier for whoever writes the next interpretation: a suggestion an accountant left for your software, an agent, or themselves. Vexless reads them back to you and never applies them. Setting them needs accounts:manage.

Roles on an origin

An origin's parties[] lists each party with the role it played on that document: BUYER or SELLER on invoices, PAYER or PAYEE on bank transactions, ISSUER for the company itself where a document carries it. counterpartyId is the one that matters for the open item: the buyer on a sale, the seller on a purchase. Postings on open-item accounts with no partyId take it.

Listing

GET /v1/companies/{companyId}/parties?externalId=&cursor=&limit=

Party merge tooling, for two records that turn out to be one legal party, is not in this version.