{ "openapi": "3.1.0", "info": { "title": "Vexless API", "version": "0.0.1", "description": "Bookkeeping as a backend. Send origins; get books, delivered invoices, sent payments, and settlement status." }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" } }, "schemas": { "Money": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Money", "type": "object", "properties": { "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ], "additionalProperties": false }, "Error": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Error", "type": "object", "properties": { "rule": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "string" } }, "required": [ "rule", "message" ], "additionalProperties": {} }, "Company": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Company", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "businessIdentifier": { "type": "string" }, "jurisdiction": { "type": "string" }, "currency": { "type": "string" }, "lockDate": { "type": [ "string", "null" ] }, "sandbox": { "type": "boolean" }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp" }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" }, "consentUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "provider", "status", "consentUrl" ], "additionalProperties": false } }, "externalAccounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connectionId": { "type": "string" }, "kind": { "type": "string" }, "externalId": { "type": "string" }, "accountNumber": { "type": "string" } }, "required": [ "id", "connectionId", "kind", "externalId", "accountNumber" ], "additionalProperties": false } }, "fiscalYears": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalYear" } } }, "required": [ "id", "name", "businessIdentifier", "jurisdiction", "currency", "lockDate", "sandbox", "createdAt", "connections", "externalAccounts", "fiscalYears" ], "additionalProperties": false }, "CompanySummary": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/CompanySummary", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "businessIdentifier": { "type": "string" }, "jurisdiction": { "type": "string" }, "currency": { "type": "string" }, "lockDate": { "type": [ "string", "null" ] }, "sandbox": { "type": "boolean" }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp" } }, "required": [ "id", "name", "businessIdentifier", "jurisdiction", "currency", "lockDate", "sandbox", "createdAt" ], "additionalProperties": false }, "FiscalYear": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/FiscalYear", "type": "object", "properties": { "id": { "type": "string" }, "startDate": { "type": "string", "description": "ISO date YYYY-MM-DD" }, "endDate": { "type": "string", "description": "ISO date YYYY-MM-DD" }, "closedAt": { "type": [ "string", "null" ] }, "closedBy": { "type": [ "string", "null" ] }, "resultAmount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "closingOriginId": { "type": [ "string", "null" ] }, "openingOriginId": { "type": [ "string", "null" ] } }, "required": [ "id", "startDate", "endDate", "closedAt", "closedBy", "resultAmount", "closingOriginId", "openingOriginId" ], "additionalProperties": false }, "Account": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Account", "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "openItems": { "type": "boolean" }, "status": { "type": "string" }, "reportingCode": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp" } }, "required": [ "id", "number", "name", "type", "openItems", "status", "reportingCode", "createdAt" ], "additionalProperties": false }, "TaxCode": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/TaxCode", "type": "object", "properties": { "jurisdiction": { "type": "string" }, "code": { "type": "string", "description": "The identity of a tax code; postings store this" }, "name": { "type": "string" }, "kind": { "type": "string" }, "rateBps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "validFrom": { "type": "string", "description": "ISO date YYYY-MM-DD" }, "validTo": { "type": [ "string", "null" ] }, "returnLine": { "type": "string" }, "vatAccountNumber": { "type": "string" } }, "required": [ "jurisdiction", "code", "name", "kind", "rateBps", "validFrom", "validTo", "returnLine", "vatAccountNumber" ], "additionalProperties": false }, "DimensionCategory": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/DimensionCategory", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "requiredOnAccounts": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "additionalProperties": false } }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "required": [ "id", "name", "requiredOnAccounts", "dimensions" ], "additionalProperties": false }, "Party": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Party", "type": "object", "properties": { "partyId": { "type": "string", "description": "Also the paging cursor" }, "name": { "type": "string", "description": "The name this company knows the party by" }, "country": { "type": [ "string", "null" ] }, "roles": { "type": "array", "items": { "type": "string" } }, "externalId": { "type": [ "string", "null" ] }, "defaultAccountNumber": { "type": [ "string", "null" ] }, "defaultTaxCode": { "type": [ "string", "null" ] }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "value": { "type": "string" }, "source": { "type": "string" } }, "required": [ "scheme", "value", "source" ], "additionalProperties": false }, "description": "Identifiers this company supplied" }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp" } }, "required": [ "partyId", "name", "country", "roles", "externalId", "defaultAccountNumber", "defaultTaxCode", "identifiers", "createdAt" ], "additionalProperties": false }, "Origin": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Origin", "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "description": "RECEIVED | POSTED | SETTLED | REJECTED | REVERSED" }, "parties": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "partyId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "externalId": { "type": [ "string", "null" ] } }, "required": [ "role", "partyId", "name", "externalId" ], "additionalProperties": false } }, "counterpartyId": { "type": [ "string", "null" ] }, "documentDate": { "type": "string", "description": "ISO date YYYY-MM-DD" }, "dueDate": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "total": { "$ref": "#/components/schemas/Money" }, "externalReference": { "type": [ "string", "null" ] }, "paymentReference": { "type": [ "string", "null" ] }, "invoiceNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "settlement": { "anyOf": [ { "$ref": "#/components/schemas/SettlementState" }, { "type": "null" } ] }, "delivery": { "anyOf": [ { "type": "object", "properties": { "channel": { "type": "string" }, "status": { "type": "string" } }, "required": [ "channel", "status" ], "additionalProperties": false }, { "type": "null" } ] }, "currentInterpretationId": { "description": "The accepted interpretation behind the current entry; null until the origin is interpreted", "type": [ "string", "null" ] }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "createdBy": { "type": "string" }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp" }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/Entry" } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "amount": { "$ref": "#/components/schemas/Money" }, "executeOn": { "type": "string", "description": "ISO date YYYY-MM-DD" }, "bankTransactionOriginId": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "amount", "executeOn", "bankTransactionOriginId" ], "additionalProperties": false } }, "interpretations": { "description": "Present with ?explain=true", "type": "array", "items": { "$ref": "#/components/schemas/Interpretation" } } }, "required": [ "id", "type", "status", "parties", "counterpartyId", "documentDate", "dueDate", "currency", "total", "externalReference", "paymentReference", "invoiceNumber", "lines", "data", "settlement", "delivery", "currentInterpretationId", "attachments", "createdBy", "createdAt", "updatedAt", "entries", "payments" ], "additionalProperties": false }, "Entry": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Entry", "type": "object", "properties": { "id": { "type": "string" }, "revision": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Bumped each time the entry is rewritten while its period is open" }, "number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "date": { "type": "string", "description": "ISO date YYYY-MM-DD" }, "description": { "type": "string" }, "originId": { "type": "string" }, "interpretationId": { "type": "string", "description": "The interpretation these postings came from" }, "actor": { "type": "string" }, "reversesEntryId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp" }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp" }, "postings": { "type": "array", "items": { "$ref": "#/components/schemas/Posting" } } }, "required": [ "id", "revision", "number", "date", "description", "originId", "interpretationId", "actor", "reversesEntryId", "createdAt", "updatedAt", "postings" ], "additionalProperties": false }, "Posting": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Posting", "type": "object", "properties": { "id": { "type": "string" }, "accountId": { "type": "string" }, "accountNumber": { "type": "string" }, "accountName": { "type": "string" }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Book currency, signed; debit positive" }, "currency": { "type": "string" }, "originalAmount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "originalCurrency": { "type": [ "string", "null" ] }, "fxRate": { "type": [ "number", "null" ] }, "partyId": { "type": [ "string", "null" ] }, "taxCode": { "type": [ "string", "null" ] }, "taxRateBps": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The rate that applied when this was booked, not the code's rate today" }, "dimensionIds": { "type": "array", "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] }, "remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Open-item accounts only; signed like amount" } }, "required": [ "id", "accountId", "accountNumber", "accountName", "amount", "currency", "originalAmount", "originalCurrency", "fxRate", "partyId", "taxCode", "taxRateBps", "dimensionIds", "description", "remaining" ], "additionalProperties": false }, "Attachment": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Attachment", "type": "object", "properties": { "id": { "type": "string" }, "originId": { "type": "string" }, "filename": { "type": "string" }, "mediaType": { "type": "string" }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hash": { "type": "string" }, "retentionUntil": { "type": [ "string", "null" ] }, "createdBy": { "type": "string" }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp" } }, "required": [ "id", "originId", "filename", "mediaType", "size", "hash", "retentionUntil", "createdBy", "createdAt" ], "additionalProperties": false }, "Interpretation": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Interpretation", "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "actor": { "type": "string", "description": "Who authored these postings" }, "status": { "type": "string", "description": "ACCEPTED | SUPERSEDED" }, "postings": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "reason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp" } }, "required": [ "id", "version", "actor", "status", "postings", "reason", "createdAt" ], "additionalProperties": false }, "SettlementState": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/SettlementState", "type": "object", "properties": { "state": { "type": "string", "enum": [ "unpaid", "partial", "settled" ] }, "paid": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paidAt": { "type": [ "string", "null" ] }, "paidBy": { "type": "array", "items": { "type": "string" }, "description": "Origins that paid this one" }, "currency": { "type": "string" } }, "required": [ "state", "paid", "remaining", "paidAt", "paidBy", "currency" ], "additionalProperties": false }, "OpenItem": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/OpenItem", "type": "object", "properties": { "id": { "type": "string", "description": "Posting id; the paging cursor" }, "postingId": { "type": "string" }, "originId": { "type": "string" }, "originType": { "type": "string" }, "entryId": { "type": "string" }, "accountNumber": { "type": "string" }, "accountName": { "type": "string" }, "partyId": { "type": [ "string", "null" ] }, "partyName": { "type": [ "string", "null" ] }, "partyExternalId": { "type": [ "string", "null" ] }, "direction": { "type": "string", "enum": [ "receivable", "payable" ] }, "amount": { "$ref": "#/components/schemas/Money" }, "remaining": { "$ref": "#/components/schemas/Money" }, "externalReference": { "type": [ "string", "null" ] }, "paymentReference": { "type": [ "string", "null" ] }, "invoiceNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "documentDate": { "type": "string", "description": "ISO date YYYY-MM-DD" }, "dueDate": { "type": [ "string", "null" ] } }, "required": [ "id", "postingId", "originId", "originType", "entryId", "accountNumber", "accountName", "partyId", "partyName", "partyExternalId", "direction", "amount", "remaining", "externalReference", "paymentReference", "invoiceNumber", "documentDate", "dueDate" ], "additionalProperties": false }, "Balances": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Balances", "type": "object", "properties": { "asOf": { "type": [ "string", "null" ] }, "from": { "description": "When set, balance is the movement in [from, asOf]", "type": [ "string", "null" ] }, "currency": { "type": "string" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string" }, "number": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "reportingCode": { "type": [ "string", "null" ] }, "balance": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "accountId", "number", "name", "type", "reportingCode", "balance" ], "additionalProperties": false } } }, "required": [ "asOf", "from", "currency", "accounts" ], "additionalProperties": false }, "IncomeStatement": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/IncomeStatement", "type": "object", "properties": { "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "code", "label", "amount" ], "additionalProperties": false } }, "result": { "$ref": "#/components/schemas/Money" } }, "required": [ "from", "to", "currency", "lines", "result" ], "additionalProperties": false }, "BalanceSheet": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/BalanceSheet", "type": "object", "properties": { "asOf": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "code", "label", "amount" ], "additionalProperties": false } }, "equityAndLiabilities": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "code", "label", "amount" ], "additionalProperties": false } }, "totals": { "type": "object", "properties": { "assets": { "$ref": "#/components/schemas/Money" }, "equityAndLiabilities": { "$ref": "#/components/schemas/Money" } }, "required": [ "assets", "equityAndLiabilities" ], "additionalProperties": false } }, "required": [ "asOf", "currency", "assets", "equityAndLiabilities", "totals" ], "additionalProperties": false }, "Settlement": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Settlement", "type": "object", "properties": { "id": { "type": "string" }, "accountNumber": { "type": "string" }, "status": { "type": "string" }, "closedAt": { "type": [ "string", "null" ] }, "closedBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp" }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "debitPostingId": { "type": "string" }, "creditPostingId": { "type": "string" }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "basis": { "type": "string" }, "actor": { "type": "string" }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp" } }, "required": [ "id", "debitPostingId", "creditPostingId", "amount", "basis", "actor", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "accountNumber", "status", "closedAt", "closedBy", "createdAt", "allocations" ], "additionalProperties": false }, "Payment": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Payment", "type": "object", "properties": { "id": { "type": "string" }, "originId": { "type": "string" }, "status": { "type": "string" }, "amount": { "$ref": "#/components/schemas/Money" }, "executeOn": { "type": "string", "description": "ISO date YYYY-MM-DD" }, "payeeIban": { "type": [ "string", "null" ] }, "paymentReference": { "type": [ "string", "null" ] }, "bankReference": { "type": [ "string", "null" ] }, "rejectReason": { "type": [ "string", "null" ] }, "bankTransactionOriginId": { "type": [ "string", "null" ] }, "actor": { "type": "string" }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp" }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp" } }, "required": [ "id", "originId", "status", "amount", "executeOn", "payeeIban", "paymentReference", "bankReference", "rejectReason", "bankTransactionOriginId", "actor", "createdAt", "updatedAt" ], "additionalProperties": false }, "Webhook": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Webhook", "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "disabledReason": { "description": "Why delivery was disabled, when it was not disabled by request", "type": [ "string", "null" ] }, "lastSuccessAt": { "anyOf": [ { "type": "string", "description": "RFC 3339 timestamp" }, { "type": "null" } ] }, "lastFailureAt": { "anyOf": [ { "type": "string", "description": "RFC 3339 timestamp" }, { "type": "null" } ] }, "consecutiveFailures": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Failed attempts since the last success" }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp" } }, "required": [ "id", "url", "events", "status", "disabledReason", "lastSuccessAt", "lastFailureAt", "consecutiveFailures", "createdAt" ], "additionalProperties": false }, "Delivery": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "#/components/schemas/Delivery", "type": "object", "properties": { "id": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "DELIVERED", "FAILED" ] }, "attempts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "lastStatus": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "HTTP status of the last attempt, or null if the request never completed" }, "lastError": { "type": [ "string", "null" ] }, "nextAttemptAt": { "anyOf": [ { "type": "string", "description": "RFC 3339 timestamp" }, { "type": "null" } ], "description": "When the next attempt is due; null once delivered or failed" }, "deliveredAt": { "anyOf": [ { "type": "string", "description": "RFC 3339 timestamp" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "description": "RFC 3339 timestamp" }, { "type": "null" } ], "description": "Set when the retry ladder ran out; no further attempts are made" }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp" } }, "required": [ "id", "eventId", "eventType", "status", "attempts", "lastStatus", "lastError", "nextAttemptAt", "deliveredAt", "failedAt", "createdAt" ], "additionalProperties": false } } }, "paths": { "/health": { "get": { "summary": "Liveness check", "tags": [ "meta" ], "description": "Scope: none.", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": false } } } } } } }, "/v1/companies": { "post": { "summary": "Create a company", "tags": [ "companies" ], "description": "Scope: any key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "businessIdentifier": { "type": "string", "minLength": 1 }, "jurisdiction": { "type": "string", "enum": [ "FI" ] }, "sandbox": { "type": "boolean" }, "fiscalYearStart": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "name", "businessIdentifier", "jurisdiction" ] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List the companies your partner holds a grant on", "tags": [ "companies" ], "description": "Scope: any key.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CompanySummary" } }, "next": { "description": "Cursor for the next page, or null", "type": [ "string", "null" ] } }, "required": [ "items", "next" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}": { "get": { "summary": "Get a company with its connections, external accounts and fiscal years", "tags": [ "companies" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/grants": { "post": { "summary": "Grant scopes on a company to a partner", "tags": [ "companies" ], "description": "Scope: grants:manage.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "granteeKind": { "type": "string", "enum": [ "VERTICAL", "OFFICE", "AGENT", "OWNER" ] }, "granteeId": { "type": "string", "minLength": 1, "description": "Partner id" }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "origins:write", "ledger:read", "settlements:write", "payments:write", "connections:manage", "review:write", "accounts:manage", "close:manage", "grants:manage" ] } } }, "required": [ "granteeKind", "granteeId", "scopes" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/grants/{grantId}": { "delete": { "summary": "Revoke a grant", "tags": [ "companies" ], "description": "Scope: grants:manage.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "grantId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/accounts": { "get": { "summary": "List the chart of accounts", "tags": [ "chart" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "next": { "description": "Cursor for the next page, or null", "type": [ "string", "null" ] } }, "required": [ "items", "next" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Add an account", "tags": [ "chart" ], "description": "Scope: accounts:manage.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "ASSET", "LIABILITY", "EQUITY", "REVENUE", "EXPENSE" ] }, "openItems": { "type": "boolean" }, "reportingCode": { "type": "string" } }, "required": [ "number", "name", "type" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tax-codes": { "get": { "summary": "List tax codes for a jurisdiction", "tags": [ "chart" ], "description": "Scope: any key.", "parameters": [ { "schema": { "default": "FI", "type": "string" }, "in": "query", "name": "jurisdiction", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TaxCode" } }, "next": { "description": "Cursor for the next page, or null", "type": [ "string", "null" ] } }, "required": [ "items", "next" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/dimensions": { "get": { "summary": "List dimension categories and dimensions", "tags": [ "chart" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionCategory" } }, "next": { "description": "Cursor for the next page, or null", "type": [ "string", "null" ] } }, "required": [ "items", "next" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a dimension, and its category on first use", "tags": [ "chart" ], "description": "Scope: origins:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "requiredOnAccounts": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] } } }, "required": [ "category", "name" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "categoryId": { "type": "string" } }, "required": [ "id", "categoryId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/parties": { "get": { "summary": "List parties as this company knows them", "tags": [ "parties" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "externalId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Party" } }, "next": { "description": "Cursor for the next page, or null", "type": [ "string", "null" ] } }, "required": [ "items", "next" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/parties/{partyId}": { "patch": { "summary": "Update your name, external id, IBAN or defaults for a party", "tags": [ "parties" ], "description": "Scope: origins:write; defaults need accounts:manage.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The name this company knows the party by", "type": "string", "minLength": 1 }, "externalId": { "type": [ "string", "null" ] }, "defaultAccountNumber": { "type": [ "string", "null" ] }, "defaultTaxCode": { "type": [ "string", "null" ] }, "iban": { "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "partyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Party" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/connections": { "post": { "summary": "Start a bank connection; returns a consent link", "tags": [ "connections" ], "description": "Scope: connections:manage.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "BANK" ] }, "provider": { "type": "string", "minLength": 1 } }, "required": [ "kind", "provider" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "consentUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "consentUrl" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/origins": { "post": { "summary": "Send a document: sales invoice, purchase invoice, bank transaction or manual entry", "tags": [ "origins" ], "description": "Scope: origins:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SALES_INVOICE" ] }, "externalReference": { "description": "Your id for the invoice", "type": "string", "minLength": 1 }, "buyer": { "type": "object", "properties": { "partyId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "businessId": { "description": "Y-tunnus / business identifier", "type": "string", "minLength": 1 }, "vatId": { "type": "string", "minLength": 1 }, "iban": { "type": "string", "minLength": 1 }, "einvoiceAddress": { "type": "string", "minLength": 1 }, "externalId": { "description": "Your id for this party", "type": "string", "minLength": 1 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "description": "Any one identifier is enough; Vexless resolves or creates the party" }, "documentDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "fxRate": { "description": "Required when currency differs from the company currency", "type": "number", "exclusiveMinimum": 0 }, "lines": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1 }, "net": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Net amount in the origin currency; negative on credit notes" }, "taxCode": { "description": "e.g. FI_SALE_25_5; company default when omitted", "type": "string" }, "vat": { "description": "Explicit VAT; authoritative on purchase invoices", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "dimensionIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "quantity": { "type": "number" }, "unit": { "type": "string" } }, "required": [ "description", "net" ] } }, "total": { "description": "Gross total as issued; validated against lines", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "postings": { "description": "What this origin means in the ledger. Omit to leave the origin awaiting an interpretation", "minItems": 2, "type": "array", "items": { "type": "object", "properties": { "accountNumber": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (cents)" }, "partyId": { "type": "string", "minLength": 1 }, "taxCode": { "type": "string" }, "dimensionIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "description": { "type": "string" } }, "required": [ "accountNumber", "amount" ] } }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "type", "buyer", "dueDate", "lines" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PURCHASE_INVOICE" ] }, "externalReference": { "description": "Supplier's invoice number", "type": "string", "minLength": 1 }, "seller": { "type": "object", "properties": { "partyId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "businessId": { "description": "Y-tunnus / business identifier", "type": "string", "minLength": 1 }, "vatId": { "type": "string", "minLength": 1 }, "iban": { "type": "string", "minLength": 1 }, "einvoiceAddress": { "type": "string", "minLength": 1 }, "externalId": { "description": "Your id for this party", "type": "string", "minLength": 1 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "description": "Any one identifier is enough; Vexless resolves or creates the party" }, "documentDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "fxRate": { "type": "number", "exclusiveMinimum": 0 }, "lines": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "minLength": 1 }, "net": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Net amount in the origin currency; negative on credit notes" }, "taxCode": { "description": "e.g. FI_SALE_25_5; company default when omitted", "type": "string" }, "vat": { "description": "Explicit VAT; authoritative on purchase invoices", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "dimensionIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "quantity": { "type": "number" }, "unit": { "type": "string" } }, "required": [ "description", "net" ] } }, "total": { "description": "Gross total as printed; validated against lines", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "paymentReference": { "description": "Supplier's payment reference (RF or Finnish)", "type": "string" }, "postings": { "description": "What this origin means in the ledger. Omit to leave the origin awaiting an interpretation", "minItems": 2, "type": "array", "items": { "type": "object", "properties": { "accountNumber": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (cents)" }, "partyId": { "type": "string", "minLength": 1 }, "taxCode": { "type": "string" }, "dimensionIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "description": { "type": "string" } }, "required": [ "accountNumber", "amount" ] } }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "type", "seller", "documentDate", "lines" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BANK_TRANSACTION" ] }, "externalId": { "type": "string", "minLength": 1, "description": "The bank's transaction id" }, "externalAccountId": { "type": "string", "minLength": 1 }, "iban": { "description": "The company's own account; alternative to externalAccountId", "type": "string" }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed; positive = money in" }, "bookingDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "valueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "counterparty": { "type": "object", "properties": { "partyId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "businessId": { "description": "Y-tunnus / business identifier", "type": "string", "minLength": 1 }, "vatId": { "type": "string", "minLength": 1 }, "iban": { "type": "string", "minLength": 1 }, "einvoiceAddress": { "type": "string", "minLength": 1 }, "externalId": { "description": "Your id for this party", "type": "string", "minLength": 1 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "description": "Any one identifier is enough; Vexless resolves or creates the party" }, "reference": { "type": "string" }, "message": { "type": "string" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "fxRate": { "type": "number", "exclusiveMinimum": 0 }, "postings": { "description": "What this origin means in the ledger. Omit to leave the origin awaiting an interpretation", "minItems": 2, "type": "array", "items": { "type": "object", "properties": { "accountNumber": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (cents)" }, "partyId": { "type": "string", "minLength": 1 }, "taxCode": { "type": "string" }, "dimensionIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "description": { "type": "string" } }, "required": [ "accountNumber", "amount" ] } }, "settles": { "description": "Origins whose open items these postings clear; needs postings", "type": "array", "items": { "type": "object", "properties": { "originId": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Integer minor units (cents)" } }, "required": [ "originId" ] } } }, "required": [ "type", "externalId", "amount", "bookingDate" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "MANUAL" ] }, "description": { "type": "string", "minLength": 1 }, "documentDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "externalReference": { "type": "string", "minLength": 1 }, "counterparty": { "type": "object", "properties": { "partyId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "businessId": { "description": "Y-tunnus / business identifier", "type": "string", "minLength": 1 }, "vatId": { "type": "string", "minLength": 1 }, "iban": { "type": "string", "minLength": 1 }, "einvoiceAddress": { "type": "string", "minLength": 1 }, "externalId": { "description": "Your id for this party", "type": "string", "minLength": 1 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "description": "Any one identifier is enough; Vexless resolves or creates the party" }, "postings": { "minItems": 2, "type": "array", "items": { "type": "object", "properties": { "accountNumber": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (cents)" }, "partyId": { "type": "string", "minLength": 1 }, "taxCode": { "type": "string" }, "dimensionIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "description": { "type": "string" } }, "required": [ "accountNumber", "amount" ] } }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "type", "description", "documentDate", "postings" ] } ] } } } }, "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "dryRun", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "description": "RECEIVED | POSTED | SETTLED | REJECTED | REVERSED" }, "parties": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "partyId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "externalId": { "type": [ "string", "null" ] } }, "required": [ "role", "partyId", "name", "externalId" ], "additionalProperties": false } }, "counterpartyId": { "type": [ "string", "null" ] }, "documentDate": { "type": "string", "description": "ISO date YYYY-MM-DD" }, "dueDate": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "total": { "$ref": "#/components/schemas/Money" }, "externalReference": { "type": [ "string", "null" ] }, "paymentReference": { "type": [ "string", "null" ] }, "invoiceNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "settlement": { "anyOf": [ { "$ref": "#/components/schemas/SettlementState" }, { "type": "null" } ] }, "delivery": { "anyOf": [ { "type": "object", "properties": { "channel": { "type": "string" }, "status": { "type": "string" } }, "required": [ "channel", "status" ], "additionalProperties": false }, { "type": "null" } ] }, "currentInterpretationId": { "description": "The accepted interpretation behind the current entry; null until the origin is interpreted", "type": [ "string", "null" ] }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "createdBy": { "type": "string" }, "createdAt": { "type": "string", "description": "RFC 3339 timestamp" }, "updatedAt": { "type": "string", "description": "RFC 3339 timestamp" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/Entry" } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "amount": { "$ref": "#/components/schemas/Money" }, "executeOn": { "type": "string", "description": "ISO date YYYY-MM-DD" }, "bankTransactionOriginId": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "amount", "executeOn", "bankTransactionOriginId" ], "additionalProperties": false } }, "interpretations": { "description": "Present with ?explain=true", "type": "array", "items": { "$ref": "#/components/schemas/Interpretation" } }, "dryRun": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "type", "status", "parties", "counterpartyId", "documentDate", "dueDate", "currency", "total", "externalReference", "paymentReference", "invoiceNumber", "lines", "data", "settlement", "delivery", "currentInterpretationId", "attachments", "createdBy", "createdAt", "updatedAt", "entries", "payments", "dryRun" ], "additionalProperties": false } } } }, "201": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Origin" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List origins", "tags": [ "origins" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "enum": [ "SALES_INVOICE", "PURCHASE_INVOICE", "BANK_TRANSACTION", "MANUAL", "SYSTEM", "PAYROLL" ] }, "in": "query", "name": "type", "required": false }, { "schema": { "type": "string", "enum": [ "RECEIVED", "POSTED", "SETTLED", "REJECTED", "REVERSED" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "partyId", "required": false }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "externalReference", "required": false }, { "schema": { "type": "string", "enum": [ "unpaid", "partial", "settled" ] }, "in": "query", "name": "settlementState", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Origin" } }, "next": { "description": "Cursor for the next page, or null", "type": [ "string", "null" ] } }, "required": [ "items", "next" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/origins/{originId}": { "get": { "summary": "Get an origin with its entries, settlement and payments", "tags": [ "origins" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "explain", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "originId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Origin" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/origins/{originId}/reverse": { "post": { "summary": "Reverse a posted origin with a negated entry", "tags": [ "origins" ], "description": "Scope: origins:write for origins you delivered; review:write for any.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "reason": { "type": "string" } } }, { "type": "null" } ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "originId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Origin" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/origins/{originId}/attachments": { "post": { "summary": "Attach a file to an origin", "tags": [ "origins" ], "description": "Scope: origins:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1 }, "mediaType": { "type": "string", "minLength": 1, "description": "e.g. application/pdf, image/jpeg" }, "contentBase64": { "type": "string", "minLength": 1, "description": "File content, base64; at most 10 MB decoded" } }, "required": [ "filename", "mediaType", "contentBase64" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "originId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List an origin's attachments", "tags": [ "origins" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "originId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "next": { "description": "Cursor for the next page, or null", "type": [ "string", "null" ] } }, "required": [ "items", "next" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/origins/{originId}/attachments/{attachmentId}": { "get": { "summary": "Download an attachment", "tags": [ "origins" ], "description": "Scope: ledger:read. Returns the file bytes with its media type; not JSON.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "originId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "attachmentId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/companies/{companyId}/origins/{originId}/reject": { "post": { "summary": "Reject an origin before it is interpreted", "tags": [ "review" ], "description": "Scope: review:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "reason": { "type": "string" } } }, { "type": "null" } ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "originId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Origin" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/origins/{originId}/interpretations": { "post": { "summary": "Say what an origin means in postings; posted in the same call", "tags": [ "review" ], "description": "Scope: origins:write for an origin still awaiting its first interpretation, review:write to re-interpret a posted one.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "postings": { "minItems": 2, "type": "array", "items": { "type": "object", "properties": { "accountNumber": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Integer minor units (cents)" }, "partyId": { "type": "string", "minLength": 1 }, "taxCode": { "type": "string" }, "dimensionIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "description": { "type": "string" } }, "required": [ "accountNumber", "amount" ] } }, "reason": { "type": "string" } }, "required": [ "postings" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "originId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Origin" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/entries": { "get": { "summary": "List current ledger entries", "tags": [ "ledger" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "account", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Entry" } }, "next": { "description": "Cursor for the next page, or null", "type": [ "string", "null" ] } }, "required": [ "items", "next" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/entries/{entryId}": { "get": { "summary": "Get an entry", "tags": [ "ledger" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "entryId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entry" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/balances": { "get": { "summary": "Balances per account, cumulative or for a range", "tags": [ "ledger" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "asOf", "required": false }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "from", "required": false, "description": "With from, balances are movements in [from, asOf]" }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "fiscalYearId", "required": false, "description": "Shorthand for from and asOf of that year" }, { "schema": { "type": "string" }, "in": "query", "name": "accounts", "required": false, "description": "Comma-separated account numbers" }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "dimensionId", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balances" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/open-items": { "get": { "summary": "Open receivables and payables", "tags": [ "ledger" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "enum": [ "receivable", "payable" ] }, "in": "query", "name": "direction", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "partyId", "required": false }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "dueBefore", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "account", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OpenItem" } }, "next": { "description": "Cursor for the next page, or null", "type": [ "string", "null" ] } }, "required": [ "items", "next" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/reports/income-statement": { "get": { "summary": "Income statement for a range or a fiscal year", "tags": [ "ledger" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "query", "name": "fiscalYearId", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncomeStatement" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/reports/balance-sheet": { "get": { "summary": "Balance sheet at a date", "tags": [ "ledger" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "in": "query", "name": "asOf", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceSheet" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/fiscal-years": { "get": { "summary": "List fiscal years", "tags": [ "close" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalYear" } }, "next": { "description": "Cursor for the next page, or null", "type": [ "string", "null" ] } }, "required": [ "items", "next" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/settlements": { "post": { "summary": "Allocate open items explicitly", "tags": [ "settlements" ], "description": "Scope: settlements:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allocations": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "debitPostingId": { "type": "string", "minLength": 1 }, "creditPostingId": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Integer minor units (cents)" } }, "required": [ "debitPostingId", "creditPostingId", "amount" ] } } }, "required": [ "allocations" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/settlements/{settlementId}": { "get": { "summary": "Get a settlement with its allocations", "tags": [ "settlements" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "settlementId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/settlements/{settlementId}/close": { "post": { "summary": "Close a settlement by booking the residual", "tags": [ "settlements" ], "description": "Scope: review:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "default": "WRITE_OFF", "type": "string", "enum": [ "WRITE_OFF", "FX_DIFFERENCE", "FEE", "YEAR_END", "VAT_SETTLEMENT" ] }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "settlementId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/payments": { "post": { "summary": "Pay a purchase invoice; the call is the approval", "tags": [ "payments" ], "description": "Scope: payments:write.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "originId": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Integer minor units (cents)" }, "executeOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "originId" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/payments/{paymentId}": { "get": { "summary": "Get a payment", "tags": [ "payments" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "paymentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/payments/{paymentId}/cancel": { "post": { "summary": "Cancel a payment that has not been sent", "tags": [ "payments" ], "description": "Scope: payments:write.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "paymentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/lock": { "post": { "summary": "Move the lock date forward", "tags": [ "close" ], "description": "Scope: close:manage.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "through" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/fiscal-years/{fiscalYearId}/close": { "post": { "summary": "Close a fiscal year: result to equity, year locked", "tags": [ "close" ], "description": "Scope: close:manage.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "fiscalYearId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalYear" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/sandbox/payments/{paymentId}/execute": { "post": { "summary": "Sandbox: the bank accepts and executes a payment", "tags": [ "sandbox" ], "description": "Scope: payments:write; sandbox companies only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "bookingDate": { "description": "Defaults to today, or to executeOn when that is in the past", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } }, { "type": "null" } ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "paymentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/sandbox/payments/{paymentId}/reject": { "post": { "summary": "Sandbox: the bank rejects a payment", "tags": [ "sandbox" ], "description": "Scope: payments:write; sandbox companies only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "reason": { "type": "string" } } }, { "type": "null" } ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "paymentId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/webhooks": { "post": { "summary": "Subscribe a URL to events", "tags": [ "webhooks" ], "description": "Scope: ledger:read. The url must be https and must resolve to a public address.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "origin.received", "origin.posted", "origin.settled", "origin.rejected", "origin.reversed", "invoice.delivered", "payment.accepted", "payment.rejected", "payment.executed", "connection.needs_auth", "company.locked", "fiscal_year.closed", "reconciliation.broken", "vat_return.filed" ] } }, "secret": { "type": "string", "minLength": 16 } }, "required": [ "url", "events" ] } } } }, "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "id", "secret" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List webhooks", "tags": [ "webhooks" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "next": { "description": "Cursor for the next page, or null", "type": [ "string", "null" ] } }, "required": [ "items", "next" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/webhooks/{webhookId}/deliveries": { "get": { "summary": "List delivery attempts for a webhook", "tags": [ "webhooks" ], "description": "Scope: ledger:read. Newest first. One row per event this webhook was sent.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "next": { "description": "Cursor for the next page, or null", "type": [ "string", "null" ] } }, "required": [ "items", "next" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/companies/{companyId}/webhooks/{webhookId}": { "delete": { "summary": "Disable a webhook", "tags": [ "webhooks" ], "description": "Scope: ledger:read.", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "companyId", "required": true }, { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "webhookId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "security": [ { "bearer": [] } ], "tags": [ { "name": "companies" }, { "name": "origins" }, { "name": "ledger" }, { "name": "settlements" }, { "name": "payments" }, { "name": "parties" }, { "name": "chart" }, { "name": "connections" }, { "name": "webhooks" }, { "name": "review", "description": "Accountant surface; scope review:write" }, { "name": "close", "description": "Accountant surface; scope close:manage" }, { "name": "sandbox", "description": "Only on sandbox companies" }, { "name": "meta" } ], "servers": [ { "url": "https://api.vexless.io", "description": "Reserved for the service; not live yet" } ] }