{ "openapi": "3.1.0", "info": { "title": "NovaFisko API", "version": "1.0.0", "summary": "Accounting platform for Belgian, French and Luxembourg firms.", "description": "REST API of NovaFisko, the one the web, desktop and mobile apps use. JSON over HTTPS, versioned in the path (`/v1`).\n\n**Conventions**\n\n- Authentication: `Authorization: Bearer ` (session token, integration token or demo token).\n- Company files and firms are addressed by their `public_token` (12 characters); every other record by its integer `id`.\n- Amounts are decimal strings with two decimals (`\"1210.00\"`), in the currency of the file. Dates are ISO 8601 (`2026-03-15`); timestamps are UTC.\n- Errors: `{message, code?, errors?}`. `message` is translated (`Accept-Language` or the language of the user), `code` is a stable machine reason when there is one, `errors` maps fields to messages on a 422.\n- A write in a locked period or a closed fiscal year answers 422 `{message, code: \"period_locked\", reason: \"period_locked\" | \"fiscal_year_closed\", errors}`.\n- Demo mode: inside the demo firm, operations flagged `x-demo-blocked` answer 403 `{message, code: \"demo_mode\"}`.\n- A company file the caller cannot see answers 404, never 403.\n- Lists are either complete arrays (reference data) or Laravel paginations (`data`, `current_page`, `last_page`, `per_page`, `total`, links) driven by `page` and `per_page`.\n- Idempotence: send `X-Client-Mutation-Id` on every write of a company file; a replay returns the memorised result with `X-Idempotent-Replay: 1`.\n- Optimistic lock: send the `version` you read as `X-Base-Version`; a stale version answers 409 `conflict`.\n- Rate limits are per route and per minute (`x-rate-limit`); beyond, 429 with `Retry-After`.\n- Deleting most records moves them to a recycle bin (`X-Trashed: 1`); posted entries are never deleted, they are reversed.", "contact": { "name": "NovaFisko", "url": "https://docs.novafisko.com", "email": "support@novafisko.com" } }, "servers": [ { "url": "https://api.novafisko.com", "description": "Production" } ], "tags": [ { "name": "Meta", "description": "Service status, connectivity probe and country packs." }, { "name": "Auth", "description": "Sign-in, account of the user, demo session." }, { "name": "Integration tokens", "description": "Long-lived tokens for server-to-server integrations, limited to the abilities `read`, `write` and `sync`." }, { "name": "Firms", "description": "Accounting firm: identity, team, assignment of the company files, activity." }, { "name": "Licence & pricing", "description": "Licence of a firm, activation keys, public price list and simulator." }, { "name": "Companies", "description": "Company files (dossiers): creation with accounting set-up, identity, settings, integrity." }, { "name": "Lookup", "description": "Company detection (CompanySearch for BE and FR, VIES elsewhere), legal forms, NACE codes, address autocompletion." }, { "name": "Chart of accounts", "description": "Accounts of a company file." }, { "name": "Journals", "description": "Journals, routing rules of the imported documents, numbering series." }, { "name": "Fiscal years", "description": "Fiscal years, periods, locking, closing and year-end." }, { "name": "Third parties", "description": "Customers and suppliers: sheet, open items, lettering, reminders, totals, VIES." }, { "name": "Entries", "description": "Journal entries: free entries, invoices and credit notes, reversal." }, { "name": "Recurring entries", "description": "Recurring entry templates and the quality checks of the file." }, { "name": "Documents", "description": "Invoices and receipts of the file: allocation, booking." }, { "name": "Document importer", "description": "Upload of PDF, images, UBL / CII XML and ZIP files, analysis, validation." }, { "name": "Bank", "description": "Bank transactions (CODA), matching, rules, treasury, SEPA payment files." }, { "name": "VAT", "description": "VAT codes, periodic declarations, Intervat XML, customer and intra-community listings." }, { "name": "Fixed assets", "description": "Fixed asset register, depreciation plans, bookings, disposals." }, { "name": "Reports", "description": "Trial balance, general ledger, balance sheet and income statement, third party and aged balances." }, { "name": "Analytics & budgets", "description": "Analytic codes, analytic report, budgets." }, { "name": "Exports", "description": "Legal books, statements and data as PDF, XLSX or CSV; full dossier as ZIP." }, { "name": "Peppol", "description": "Registration of a company file on Peppol, transport options, network lookups." }, { "name": "Integrations", "description": "Catalogue of integrations, Novadesko synchronisation, file relays." }, { "name": "History & recycle bin", "description": "Version history, revert, recycle bin, activity feed." }, { "name": "Synchronisation", "description": "Continuous and offline synchronisation: bootstrap, pull, push, conflicts. Requires the `sync` ability for integration tokens." }, { "name": "Mail", "description": "Mails sent to clients in the name of the firm, shared files." }, { "name": "Webhooks", "description": "Outgoing webhooks of a firm: endpoints, test event, delivery log." }, { "name": "Novadesko bridge", "description": "Endpoints reserved to the Novadesko platform (shared secret)." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/": { "get": { "operationId": "root", "tags": [ "Meta" ], "summary": "API root", "description": "Name and version of the API.\n\nPublic endpoint: no bearer token.", "x-route-name": "api.root", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "NovaFisko API" }, "version": { "type": "string", "example": "v1" }, "status": { "type": "string", "example": "ok" } } } } } } } } }, "/v1/status": { "get": { "operationId": "status", "tags": [ "Meta" ], "summary": "Service status", "description": "Public endpoint: no bearer token.", "x-route-name": "api.v1.status", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "time": { "type": "string", "format": "date-time" } } } } } } } } }, "/v1/ping": { "get": { "operationId": "ping", "tags": [ "Meta" ], "summary": "Connectivity probe", "description": "Cheap probe without database access. The apps call it to leave offline mode; integrations can use it as a health check and to read the server clock.\n\nPublic endpoint: no bearer token.", "x-route-name": "api.v1.ping", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "server_time": { "type": "string", "format": "date-time" } } } } } } } } }, "/v1/country-packs": { "get": { "operationId": "country-packs", "tags": [ "Meta" ], "summary": "Available country packs", "description": "Country packs (chart of accounts, VAT codes, journals) a company file can be created with.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.country-packs", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "BE", "FR", "LU" ] }, "currency": { "type": "string", "example": "EUR" }, "vat_regimes": { "type": "array", "items": { "type": "string", "enum": [ "monthly", "quarterly", "franchise", "exempt", "unit" ] } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/auth/login": { "post": { "operationId": "auth.login", "tags": [ "Auth" ], "summary": "Sign in", "description": "Exchanges an e-mail and a password for a session token (all abilities). Novadesko fiduciary users sign in with their Novadesko credentials: firm, team and company files are mirrored at each sign-in. Ten failed attempts per IP lock the sign-in for five minutes.\n\nPublic endpoint: no bearer token.\n\nRate limit: 20 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.auth.login", "x-rate-limit": { "limit": 20, "window_minutes": 1 }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "example": "••••••••" }, "device_name": { "type": "string", "example": "MacBook de Claire", "description": "Label of the token (100 characters max)." } }, "required": [ "email", "password" ] }, "example": { "email": "claire.dumont@fiduciaire-dumont.be", "password": "correct horse battery staple", "device_name": "ERP connector" } } } }, "responses": { "201": { "description": "Signed in", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Bearer token, shown once." }, "user": { "$ref": "#/components/schemas/User" } } }, "example": { "token": "57|Qm9x2kL8vT4nR7sW1pZ5cY3hJ6dF0gA9bE2uI4oK", "user": { "id": 12, "name": "Claire Dumont", "email": "claire.dumont@fiduciaire-dumont.be", "locale": "fr", "email_verified": true, "pending_email": null, "is_platform_admin": false, "is_demo": false, "firms": [ { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés", "role": "admin" } ], "managed_firms": [ { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés" } ] } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/demo": { "post": { "operationId": "auth.demo", "tags": [ "Auth" ], "summary": "Sign in to the demo", "description": "Creates an ephemeral user attached to the demo firm (« Fiduciaire Démo », four realistic Belgian company files) and returns its token. Local bookkeeping is allowed (entries, lettering, VAT declarations, exports, history, recycle bin, synchronisation); every external effect answers 403 `demo_mode`: Peppol, Novadesko, e-mails and reminders, integrations, licence keys, team and firm management, company creation and deletion, webhooks and integration tokens, company lookups and VIES, uploads and analysis of the document importer, SEPA files (operations flagged `x-demo-blocked`). A demo user never reaches anything outside the demo firm (404). The demo data is reset every night and demo users are purged after 24 hours.\n\nPublic endpoint: no bearer token.\n\nRate limit: 10 requests per minute (429 beyond, see `Retry-After`).\n\nError codes (`code`):\n- `demo_unavailable`: the demo data set is not available right now", "x-route-name": "api.v1.auth.demo", "x-rate-limit": { "limit": 10, "window_minutes": 1 }, "x-error-codes": [ "demo_unavailable" ], "security": [], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] }, "device_name": { "type": "string", "description": "100 characters max." } } }, "example": { "locale": "fr" } } } }, "responses": { "201": { "description": "Demo session opened", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "user": { "$ref": "#/components/schemas/User" }, "demo": { "type": "object", "properties": { "firm": { "type": "object", "properties": { "public_token": { "type": "string", "minLength": 12, "maxLength": 12 }, "name": { "type": "string", "example": "Fiduciaire Démo" } } }, "companies": { "type": "array", "items": { "type": "object", "properties": { "public_token": { "type": "string", "minLength": 12, "maxLength": 12 }, "code": { "type": "string", "example": "COMPTOIR" }, "name": { "type": "string", "example": "Le Comptoir Montois SRL" } } } }, "expires_at": { "type": "string", "format": "date-time", "description": "End of life of the demo user." }, "resets_at": { "type": "string", "format": "date-time", "description": "Next nightly reset of the demo data." } } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "description": "The demo firm is not seeded (`demo_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "La démonstration est momentanément indisponible.", "code": "demo_unavailable" } } } } } } }, "/v1/auth/me": { "get": { "operationId": "auth.me", "tags": [ "Auth" ], "summary": "Current user", "description": "User behind the token, with the firms it belongs to and `is_demo`.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.auth.me", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "example": { "id": 12, "name": "Claire Dumont", "email": "claire.dumont@fiduciaire-dumont.be", "locale": "fr", "email_verified": true, "pending_email": null, "is_platform_admin": false, "is_demo": false, "firms": [ { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés", "role": "admin" } ], "managed_firms": [ { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/auth/logout": { "post": { "operationId": "auth.logout", "tags": [ "Auth" ], "summary": "Sign out", "description": "Revokes the token used for the request.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.auth.logout", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "204": { "description": "Token revoked." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/auth/forgot-password": { "post": { "operationId": "auth.forgot-password", "tags": [ "Auth" ], "summary": "Ask for a password reset", "description": "Always answers the same generic message, whether the account exists or not.\n\nPublic endpoint: no bearer token.\n\nRate limit: 5 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.auth.forgot-password", "x-rate-limit": { "limit": 5, "window_minutes": 1 }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "locale": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/reset-password": { "post": { "operationId": "auth.reset-password", "tags": [ "Auth" ], "summary": "Reset the password", "description": "With the token of the reset mail. Every device is signed out.\n\nPublic endpoint: no bearer token.\n\nRate limit: 10 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.auth.reset-password", "x-rate-limit": { "limit": 10, "window_minutes": 1 }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "description": "8 characters at least." }, "password_confirmation": { "type": "string" } }, "required": [ "token", "email", "password", "password_confirmation" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/email/verify/{id}/{hash}": { "get": { "operationId": "auth.email.verify", "tags": [ "Auth" ], "summary": "Confirm an e-mail address", "description": "Signed link of the verification mail. Opened in a browser it redirects to the app; with `format=json` it answers JSON.\n\nAuthorised by the signature of the URL (query parameters `signature` and `expires`), not by a bearer token. The URL is issued by another endpoint and expires.\n\nRate limit: 30 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.auth.email.verify", "x-signed-url": true, "x-rate-limit": { "limit": 30, "window_minutes": 1 }, "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "name": "hash", "in": "path", "required": true, "description": "SHA-1 of the e-mail address being confirmed.", "schema": { "type": "string" }, "example": "5f2b8c…" }, { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Expires" }, { "name": "format", "in": "query", "description": "Answer JSON instead of redirecting.", "schema": { "type": "string", "enum": [ "json" ] } } ], "responses": { "200": { "description": "Confirmed (`format=json`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "302": { "description": "Redirection to app.novafisko.com/email-verified.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Target of the redirection." } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Invalid or outdated link (`format=json`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "type": "boolean", "example": false } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/change-password": { "post": { "operationId": "auth.change-password", "tags": [ "Auth" ], "summary": "Change the password", "description": "Refused for accounts whose password is managed by Novadesko.\n\nSession token only: integration tokens are refused with 403 `session_token_required`.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 10 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.auth.change-password", "x-session-token-only": true, "x-demo-blocked": true, "x-rate-limit": { "limit": 10, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "current_password": { "type": "string" }, "password": { "type": "string", "description": "8 characters at least, different from the current one." }, "password_confirmation": { "type": "string" } }, "required": [ "current_password", "password", "password_confirmation" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/change-email": { "post": { "operationId": "auth.change-email", "tags": [ "Auth" ], "summary": "Change the e-mail address", "description": "The current password is asked again; the new address replaces the old one once confirmed.\n\nSession token only: integration tokens are refused with 403 `session_token_required`.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 6 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.auth.change-email", "x-session-token-only": true, "x-demo-blocked": true, "x-rate-limit": { "limit": 6, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "pending_email": { "type": "string", "format": "email" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/email/resend": { "post": { "operationId": "auth.email.resend", "tags": [ "Auth" ], "summary": "Send the confirmation mail again", "description": "Session token only: integration tokens are refused with 403 `session_token_required`.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 6 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.auth.email.resend", "x-session-token-only": true, "x-demo-blocked": true, "x-rate-limit": { "limit": 6, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "boolean" }, "message": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/notification-preferences": { "get": { "operationId": "auth.notification-preferences", "tags": [ "Auth" ], "summary": "Mail notification preferences", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.auth.notification-preferences", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "account", "firm", "billing", "documents", "integrations", "platform" ] }, "label": { "type": "string", "example": "Documents" }, "description": { "type": "string" }, "locked": { "type": "boolean", "description": "Locked categories (account security) cannot be switched off." }, "enabled": { "type": "boolean" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "patch": { "operationId": "auth.notification-preferences.update", "tags": [ "Auth" ], "summary": "Update the notification preferences", "description": "Locked categories and unknown keys are ignored.\n\nSession token only: integration tokens are refused with 403 `session_token_required`.", "x-route-name": "api.v1.auth.notification-preferences.update", "x-session-token-only": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prefs": { "type": "object", "description": "Category => enabled.", "additionalProperties": { "type": "boolean" } } }, "required": [ "prefs" ] }, "example": { "prefs": { "documents": true, "billing": false } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "account", "firm", "billing", "documents", "integrations", "platform" ] }, "label": { "type": "string", "example": "Documents" }, "description": { "type": "string" }, "locked": { "type": "boolean", "description": "Locked categories (account security) cannot be switched off." }, "enabled": { "type": "boolean" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/auth/tokens": { "get": { "operationId": "auth.tokens.index", "tags": [ "Integration tokens" ], "summary": "List the integration tokens", "description": "Integration tokens of the current user. The secret is never returned again.\n\nSession token only: integration tokens are refused with 403 `session_token_required`.", "x-route-name": "api.v1.auth.tokens.index", "x-session-token-only": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationToken" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "auth.tokens.store", "tags": [ "Integration tokens" ], "summary": "Create an integration token", "description": "Long-lived token for a server-to-server integration, limited to the chosen abilities:\n\n- `read`: every GET;\n- `write`: POST, PUT, PATCH and DELETE;\n- `sync`: the offline synchronisation endpoints (`sync/bootstrap`, `sync/pull`, `sync/push`, `sync/status`, `sync/conflicts`).\n\nThe token acts with the rights of the user who created it (same firms, same company files). The plain token is shown once: store it in a secret manager.\n\nSession token only: integration tokens are refused with 403 `session_token_required`.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 20 requests per minute (429 beyond, see `Retry-After`).\n\nError codes (`code`):\n- `token_limit_reached`: 50 integration tokens per user at most", "x-route-name": "api.v1.auth.tokens.store", "x-session-token-only": true, "x-demo-blocked": true, "x-rate-limit": { "limit": 20, "window_minutes": 1 }, "x-error-codes": [ "token_limit_reached" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Label (100 characters max)." }, "abilities": { "type": "array", "items": { "type": "string", "enum": [ "read", "write", "sync" ] } }, "expires_in_days": { "type": [ "integer", "null" ], "description": "1 to 730; null or absent = no expiry." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Alternative to `expires_in_days`: a future date, 730 days ahead at most." } }, "required": [ "name", "abilities" ] }, "example": { "name": "ERP connector", "abilities": [ "read", "sync" ], "expires_in_days": 365 } } } }, "responses": { "201": { "description": "Token created (`data` and `integration_token` are the same object)", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Plain token (id, a pipe, then the secret), shown once." }, "data": { "$ref": "#/components/schemas/IntegrationToken" }, "integration_token": { "$ref": "#/components/schemas/IntegrationToken" } } }, "example": { "token": "57|Qm9x2kL8vT4nR7sW1pZ5cY3hJ6dF0gA9bE2uI4oK", "data": { "id": 57, "name": "ERP connector", "abilities": [ "read", "sync" ], "created_at": "2026-10-05T09:12:44+00:00", "expires_at": "2027-10-05T09:12:44+00:00", "last_used_at": null }, "integration_token": { "id": 57, "name": "ERP connector", "abilities": [ "read", "sync" ], "created_at": "2026-10-05T09:12:44+00:00", "expires_at": "2027-10-05T09:12:44+00:00", "last_used_at": null } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/auth/tokens/{token}": { "delete": { "operationId": "auth.tokens.destroy", "tags": [ "Integration tokens" ], "summary": "Revoke an integration token", "description": "Only the integration tokens of the current user; anything else answers 404.\n\nSession token only: integration tokens are refused with 403 `session_token_required`.\n\nNot available in demo mode: answers 403 `demo_mode`.", "x-route-name": "api.v1.auth.tokens.destroy", "x-session-token-only": true, "x-demo-blocked": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Id of the integration token.", "schema": { "type": "integer" }, "example": 57 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "204": { "description": "Token revoked." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/firms/{firm}": { "get": { "operationId": "firms.show", "tags": [ "Firms" ], "summary": "Firm, team and company files", "description": "Any active member of the firm can read it.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.firms.show", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Firm" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "firms.update", "tags": [ "Firms" ], "summary": "Update the identity of the firm", "description": "Admins and managers of the firm.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.", "x-route-name": "api.v1.firms.update", "x-required-ability": "write", "x-demo-blocked": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "200 characters max." }, "enterprise_number": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ] }, "itaa_number": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2." }, "locale": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } } }, "example": { "phone": "+32 65 31 42 18", "website": "https://www.fiduciaire-dumont.be" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Firm" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/firms/{firm}/sync": { "post": { "operationId": "firms.sync", "tags": [ "Firms" ], "summary": "Resynchronise the firm from Novadesko", "description": "Identity, members and company files of a firm linked to Novadesko. 422 when the firm is not linked, 503 when Novadesko does not answer.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 6 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.firms.sync", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 6, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Firm" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/firms/{firm}/members": { "post": { "operationId": "firms.members.store", "tags": [ "Firms" ], "summary": "Add a member", "description": "Attaches an existing user (by e-mail) or creates the account (`password` required then). 201 when the account was created, 200 when an existing user was attached.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nError codes (`code`):\n- `user_limit_reached`: the licence does not allow one more user", "x-route-name": "api.v1.firms.members.store", "x-required-ability": "write", "x-demo-blocked": true, "x-error-codes": [ "user_limit_reached" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string", "description": "Required for a new account." }, "password": { "type": [ "string", "null" ], "description": "8 characters at least; required for a new account." }, "role": { "type": "string", "enum": [ "admin", "manager", "encoder", "reviewer" ] }, "locale": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] }, "company_tokens": { "type": "array", "items": { "type": "string", "minLength": 12, "maxLength": 12, "description": "Company files assigned (encoder role)." } } }, "required": [ "email", "role" ] }, "example": { "email": "thomas.peeters@fiduciaire-dumont.be", "name": "Thomas Peeters", "password": "S3cure-Pass!", "role": "encoder", "company_tokens": [ "XBVD5O1L29HC" ] } } } }, "responses": { "200": { "description": "Existing user attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmMember" } } } }, "201": { "description": "Account created and attached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmMember" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/firms/{firm}/members/{user}": { "patch": { "operationId": "firms.members.update", "tags": [ "Firms" ], "summary": "Update a member", "description": "Role, activation, name, password. The last active admin cannot lose its role.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.", "x-route-name": "api.v1.firms.members.update", "x-required-ability": "write", "x-demo-blocked": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "name": "user", "in": "path", "required": true, "description": "Id of the user (member of the firm).", "schema": { "type": "integer" }, "example": 12 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "manager", "encoder", "reviewer" ] }, "is_active": { "type": "boolean" }, "name": { "type": "string" }, "password": { "type": [ "string", "null" ] } } }, "example": { "role": "manager" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmMember" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "operationId": "firms.members.destroy", "tags": [ "Firms" ], "summary": "Remove a member", "description": "Detaches the user from the firm and from its company files. The user account itself is kept.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.", "x-route-name": "api.v1.firms.members.destroy", "x-required-ability": "write", "x-demo-blocked": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "name": "user", "in": "path", "required": true, "description": "Id of the user (member of the firm).", "schema": { "type": "integer" }, "example": 12 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "204": { "description": "Done, no body." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/firms/{firm}/members/{user}/companies": { "put": { "operationId": "firms.members.companies", "tags": [ "Firms" ], "summary": "Replace the company files of a member", "description": "Integration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.", "x-route-name": "api.v1.firms.members.companies", "x-required-ability": "write", "x-demo-blocked": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "name": "user", "in": "path", "required": true, "description": "Id of the user (member of the firm).", "schema": { "type": "integer" }, "example": 12 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_tokens": { "type": "array", "items": { "type": "string", "minLength": 12, "maxLength": 12 } }, "role": { "type": "string", "enum": [ "manager", "encoder", "reviewer" ] } }, "required": [ "company_tokens" ] }, "example": { "company_tokens": [ "XBVD5O1L29HC", "K7MPL2QX9ZTA" ], "role": "encoder" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmMember" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/firms/{firm}/companies/{company}/members": { "put": { "operationId": "firms.companies.members", "tags": [ "Firms" ], "summary": "Replace the members of a company file", "description": "Integration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.", "x-route-name": "api.v1.firms.companies.members", "x-required-ability": "write", "x-demo-blocked": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "integer" }, "role": { "type": "string", "enum": [ "manager", "encoder", "reviewer" ] } }, "required": [ "user_id" ] } } }, "required": [ "members" ] }, "example": { "members": [ { "user_id": 12, "role": "manager" }, { "user_id": 15, "role": "encoder" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Firm" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/firms/{firm}/activity": { "get": { "operationId": "firms.activity", "tags": [ "Firms" ], "summary": "Activity of the firm", "description": "Audit trail and history merged, newest first, for every company file of the firm. Admins and managers only (404 otherwise).\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.firms.activity", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "name": "company", "in": "query", "description": "Restrict to one company file.", "schema": { "type": "string", "minLength": 12, "maxLength": 12 } }, { "name": "user_id", "in": "query", "schema": { "type": "integer" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "type", "in": "query", "description": "Action or subject type.", "schema": { "type": "string" } }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "audit", "revision" ] } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityFeed" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/firms/{firm}/files/view": { "get": { "operationId": "firms.files.view", "tags": [ "Firms" ], "summary": "Signed relay of a firm file", "description": "Serves the logo of a firm stored on Novadesko with CORS headers. The signed URL is found in `logo_url` of the firm payload.\n\nAuthorised by the signature of the URL (query parameters `signature` and `expires`), not by a bearer token. The URL is issued by another endpoint and expires.\n\nRate limit: 120 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.firms.files.view", "x-signed-url": true, "x-rate-limit": { "limit": 120, "window_minutes": 1 }, "security": [], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Expires" }, { "name": "url", "in": "query", "required": true, "description": "Relayed file.", "schema": { "type": "string", "format": "uri" } } ], "responses": { "200": { "description": "The file, inline.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/firms/{firm}/licence": { "get": { "operationId": "firms.licence", "tags": [ "Licence & pricing" ], "summary": "Licence of the firm", "description": "Plan, status, usage of the month, estimate of the next invoice, entitlements and limits.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.firms.licence", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Licence" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/firms/{firm}/licence/activate": { "post": { "operationId": "firms.licence.activate", "tags": [ "Licence & pricing" ], "summary": "Activate a licence key", "description": "Creates or replaces the subscription of the firm.\n\nSession token only: integration tokens are refused with 403 `session_token_required`.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 10 requests per minute (429 beyond, see `Retry-After`).\n\nError codes (`code`):\n- `invalid_key`: unknown key\n- `expired_key`: key past its validity\n- `exhausted_key`: every activation of the key is used\n- `key_reserved`: key reserved for another firm\n- `already_active`: the key is already active on this firm", "x-route-name": "api.v1.firms.licence.activate", "x-session-token-only": true, "x-demo-blocked": true, "x-rate-limit": { "limit": 10, "window_minutes": 1 }, "x-error-codes": [ "invalid_key", "expired_key", "exhausted_key", "key_reserved", "already_active" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "example": "NVFK-7Q2M-X4TA-9LDP", "description": "Licence key." } }, "required": [ "key" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Licence" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/firms/{firm}/licence/activation": { "delete": { "operationId": "firms.licence.release", "tags": [ "Licence & pricing" ], "summary": "Release the licence key", "description": "The subscription that depends on the key is cancelled.\n\nSession token only: integration tokens are refused with 403 `session_token_required`.\n\nNot available in demo mode: answers 403 `demo_mode`.", "x-route-name": "api.v1.firms.licence.release", "x-session-token-only": true, "x-demo-blocked": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Licence" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/pricing": { "get": { "operationId": "pricing", "tags": [ "Licence & pricing" ], "summary": "Public price list", "description": "Plans, tiers and options, excl. VAT, per month. Cached five minutes.\n\nPublic endpoint: no bearer token.\n\nRate limit: 120 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.pricing", "x-rate-limit": { "limit": 120, "window_minutes": 1 }, "security": [], "parameters": [ { "name": "locale", "in": "query", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingGrid" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/pricing/simulate": { "get": { "operationId": "pricing.simulate", "tags": [ "Licence & pricing" ], "summary": "Price simulator", "description": "Public endpoint: no bearer token.\n\nRate limit: 120 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.pricing.simulate", "x-rate-limit": { "limit": 120, "window_minutes": 1 }, "security": [], "parameters": [ { "name": "companies", "in": "query", "required": true, "description": "Number of company files.", "schema": { "type": "integer" }, "example": 25 }, { "name": "client_portal", "in": "query", "description": "Clients with the portal option.", "schema": { "type": "integer" } }, { "name": "client_invoicing", "in": "query", "description": "Clients with the invoicing option.", "schema": { "type": "integer" } }, { "name": "yearly", "in": "query", "description": "Yearly billing.", "schema": { "type": "string", "enum": [ "0", "1", "true", "false" ] } }, { "name": "locale", "in": "query", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingSimulation" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies": { "get": { "operationId": "companies.index", "tags": [ "Companies" ], "summary": "List the company files", "description": "Every company file the user can open: all files of the firms it administers or manages, plus the files it is assigned to.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "companies.store", "tags": [ "Companies" ], "summary": "Create a company file", "description": "Creates the file and initialises its accounting: chart of accounts of the country pack (PCMN for BE), VAT codes, journals (ACH, NCA, VEN, NCV, OD, CAI and one financial journal per bank) and the first fiscal year with its periods. `firm` is optional when the user manages exactly one firm; without a firm the file is standalone.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nError codes (`code`):\n- `company_limit_reached`: the licence or the plan does not allow one more company file", "x-route-name": "api.v1.companies.store", "x-required-ability": "write", "x-demo-blocked": true, "x-error-codes": [ "company_limit_reached" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firm": { "type": [ "string", "null" ], "minLength": 12, "maxLength": 12, "description": "Firm that manages the file." }, "country_pack": { "type": "string", "enum": [ "BE", "FR", "LU" ] }, "code": { "type": [ "string", "null" ], "description": "Short code, letters, digits, dash, underscore (20 max)." }, "name": { "type": "string", "description": "200 characters max." }, "enterprise_number": { "type": [ "string", "null" ], "description": "Checked against the country rules (BE: modulo 97)." }, "vat_number": { "type": [ "string", "null" ], "description": "Format and check digits validated per country." }, "legal_form": { "type": [ "string", "null" ] }, "legal_form_code": { "type": [ "string", "null" ], "description": "Code of `GET /v1/reference/legal-forms`." }, "address": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ], "format": "uri" }, "vat_regime": { "type": "string", "enum": [ "monthly", "quarterly", "franchise", "exempt", "unit" ] }, "locale": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] }, "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "box": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2." }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "nace_codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "classification": { "type": "string", "enum": [ "MAIN", "SECO", "ANCI" ] } }, "required": [ "code" ] } }, "main_nace_code": { "type": [ "string", "null" ] }, "fiscal_year": { "type": "object", "properties": { "code": { "type": "string", "description": "10 characters max." }, "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" } }, "required": [ "starts_on", "ends_on" ] }, "banks": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Journal code, 6 characters max." }, "label": { "type": "string" }, "iban": { "type": [ "string", "null" ] } }, "required": [ "code", "label" ] } } }, "required": [ "name" ] }, "example": { "firm": "NDTQVQU4AUAV", "country_pack": "BE", "code": "COMPTOIR", "name": "Le Comptoir Montois SRL", "enterprise_number": "0477.472.701", "legal_form_code": "610", "vat_regime": "quarterly", "street": "Grand-Place", "house_number": "14", "postal_code": "7000", "city": "Mons", "fiscal_year": { "code": "2026", "starts_on": "2026-01-01", "ends_on": "2026-12-31" }, "banks": [ { "code": "BNP", "label": "BNP Paribas Fortis", "iban": "BE68 5390 0754 7034" } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}": { "get": { "operationId": "companies.show", "tags": [ "Companies" ], "summary": "Company file", "description": "With its fiscal years, periods and journals.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.show", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "companies.update", "tags": [ "Companies" ], "summary": "Update a company file", "description": "Identity and / or `settings`. Settings are merged key by key: send only the keys to change; only known keys are accepted.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.update", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Short code, letters, digits, dash, underscore (20 max)." }, "name": { "type": "string", "description": "200 characters max." }, "enterprise_number": { "type": [ "string", "null" ], "description": "Checked against the country rules (BE: modulo 97)." }, "vat_number": { "type": [ "string", "null" ], "description": "Format and check digits validated per country." }, "legal_form": { "type": [ "string", "null" ] }, "legal_form_code": { "type": [ "string", "null" ], "description": "Code of `GET /v1/reference/legal-forms`." }, "address": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ], "format": "uri" }, "vat_regime": { "type": "string", "enum": [ "monthly", "quarterly", "franchise", "exempt", "unit" ] }, "locale": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] }, "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "box": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2." }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "nace_codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "classification": { "type": "string", "enum": [ "MAIN", "SECO", "ANCI" ] } }, "required": [ "code" ] } }, "main_nace_code": { "type": [ "string", "null" ] }, "settings": { "$ref": "#/components/schemas/CompanySettings" } } }, "example": { "vat_regime": "monthly", "settings": { "vat": { "office_number": "0420" }, "auto_entries": { "reconciliation_difference": { "max_amount": 2.5 } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "operationId": "companies.destroy", "tags": [ "Companies" ], "summary": "Delete a company file", "description": "Soft delete: the file disappears from every list.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.", "x-route-name": "api.v1.companies.destroy", "x-required-ability": "write", "x-demo-blocked": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "responses": { "204": { "description": "Done, no body.", "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-Trashed": { "$ref": "#/components/headers/X-Trashed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/companies/{company}/integrity": { "get": { "operationId": "companies.integrity", "tags": [ "Companies" ], "summary": "Integrity check", "description": "Sum of debits and credits over every entry of the file.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.integrity", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "debit": { "type": "number", "example": 184320.55 }, "credit": { "type": "number", "example": 184320.55 }, "entries": { "type": "integer", "example": 1284 }, "is_balanced": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/settings": { "get": { "operationId": "companies.settings", "tags": [ "Companies" ], "summary": "Resolved settings", "description": "Settings of the file with the journals available for the selectors.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.settings", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/CompanySettings" }, "journals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "code": { "type": "string", "example": "OD" }, "label": { "type": "string", "example": "Opérations diverses" }, "type": { "type": "string", "example": "miscellaneous" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/sheet": { "get": { "operationId": "companies.sheet", "tags": [ "Lookup" ], "summary": "Company sheet of the file", "description": "Sheet stored on the file (last detection), structured address, legal form, NACE codes and map links.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.sheet", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SheetView" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/apply-sheet": { "post": { "operationId": "companies.apply-sheet", "tags": [ "Lookup" ], "summary": "Fill the file from a company sheet", "description": "Looks the company up and copies name, legal form, address, NACE codes and VAT number to the file (empty fields only unless `overwrite`).\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 30 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.apply-sheet", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 30, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "example": "0477472701", "description": "Enterprise or VAT number." }, "refresh": { "type": [ "boolean", "null" ], "description": "Ignore the 24 h cache." }, "overwrite": { "type": [ "boolean", "null" ], "description": "Replace the fields already filled in." } }, "required": [ "identifier" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/Company" }, "sheet": { "$ref": "#/components/schemas/CompanySheet" }, "map": { "type": "object", "additionalProperties": true } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/companies/{company}/third-parties/{thirdParty}/sheet": { "get": { "operationId": "companies.third-parties.sheet", "tags": [ "Lookup" ], "summary": "Company sheet of a third party", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.third-parties.sheet", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "thirdParty", "in": "path", "required": true, "description": "Id of the third party.", "schema": { "type": "integer" }, "example": 18 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SheetView" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/third-parties/{thirdParty}/apply-sheet": { "post": { "operationId": "companies.third-parties.apply-sheet", "tags": [ "Lookup" ], "summary": "Fill a third party from a company sheet", "description": "Integration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 30 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.third-parties.apply-sheet", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 30, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "thirdParty", "in": "path", "required": true, "description": "Id of the third party.", "schema": { "type": "integer" }, "example": 18 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "example": "0477472701", "description": "Enterprise or VAT number." }, "refresh": { "type": [ "boolean", "null" ], "description": "Ignore the 24 h cache." }, "overwrite": { "type": [ "boolean", "null" ], "description": "Replace the fields already filled in." } }, "required": [ "identifier" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "third_party": { "$ref": "#/components/schemas/ThirdParty" }, "sheet": { "$ref": "#/components/schemas/CompanySheet" }, "map": { "type": "object", "additionalProperties": true } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/reference/legal-forms": { "get": { "operationId": "reference.legal-forms", "tags": [ "Lookup" ], "summary": "Legal forms", "description": "Official nomenclature of legal forms (KBO / BCE for Belgium).\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.reference.legal-forms", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "country", "in": "query", "description": "ISO country, BE by default.", "schema": { "type": "string" }, "example": "BE" }, { "name": "q", "in": "query", "description": "Code, abbreviation or label.", "schema": { "type": "string" }, "example": "srl" }, { "name": "common", "in": "query", "description": "Only the common forms.", "schema": { "type": "boolean" } }, { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "610" }, "label": { "type": "string", "example": "Société à responsabilité limitée" }, "label_fr": { "type": "string" }, "label_nl": { "type": "string", "example": "Besloten Vennootschap" }, "label_de": { "type": "string" }, "label_en": { "type": "string" }, "abbreviation": { "type": [ "string", "null" ], "example": "SRL" }, "is_common": { "type": "boolean" } } } }, "country": { "type": "string", "example": "BE" }, "nomenclature_country": { "type": "string", "example": "BE" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/reference/nace": { "get": { "operationId": "reference.nace", "tags": [ "Lookup" ], "summary": "NACE codes", "description": "Search in the NACE-BEL nomenclature by code or words.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.reference.nace", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "BE" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "example": "restauration" }, { "name": "limit", "in": "query", "description": "1 to 200, 30 by default.", "schema": { "type": "integer" } }, { "name": "level", "in": "query", "description": "1 to 7.", "schema": { "type": "integer" } }, { "name": "edition", "in": "query", "schema": { "type": "string" }, "example": "2025" }, { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "56111" }, "label": { "type": "string", "example": "Restauration à service complet" }, "label_fr": { "type": "string" }, "label_nl": { "type": "string" }, "label_de": { "type": "string" }, "label_en": { "type": "string" }, "level": { "type": "integer", "example": 5 }, "edition": { "type": "string", "example": "2025" } } } }, "country": { "type": "string" }, "nomenclature_country": { "type": "string" }, "locale": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/lookup/capabilities": { "get": { "operationId": "lookup.capabilities", "tags": [ "Lookup" ], "summary": "Lookup capabilities of a country", "description": "What the detection can do for a country: BE and FR through CompanySearch (search, sheet, cities, streets), other EU countries through VIES (VAT check only).\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.lookup.capabilities", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "BE" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string", "example": "BE" }, "search": { "type": "boolean" }, "sheet": { "type": "boolean" }, "vat": { "type": "boolean" }, "cities": { "type": "boolean" }, "streets": { "type": "boolean" }, "source": { "type": "string", "example": "companysearch" }, "provider_configured": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/lookup/search": { "get": { "operationId": "lookup.search", "tags": [ "Lookup" ], "summary": "Search a company by name or number", "description": "Integration tokens need the `read` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 60 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.lookup.search", "x-required-ability": "read", "x-demo-blocked": true, "x-rate-limit": { "limit": 60, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "description": "2 characters at least.", "schema": { "type": "string" }, "example": "comptoir montois" }, { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "BE" }, { "name": "limit", "in": "query", "description": "1 to 25.", "schema": { "type": "integer" } }, { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string", "example": "0477472701" }, "name": { "type": "string", "example": "Le Comptoir Montois" }, "legal_form": { "type": [ "string", "null" ], "example": "SRL" }, "vat_number": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ], "example": "7000" }, "city": { "type": [ "string", "null" ], "example": "Mons" }, "status": { "type": [ "string", "null" ], "example": "active" } } } }, "search_supported": { "type": "boolean" }, "provider_configured": { "type": "boolean" }, "source": { "type": "string" }, "country": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/lookup/companies/{identifier}": { "get": { "operationId": "lookup.companies.show", "tags": [ "Lookup" ], "summary": "Company sheet", "description": "Normalised sheet of a company, cached 24 hours.\n\nIntegration tokens need the `read` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 60 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.lookup.companies.show", "x-required-ability": "read", "x-demo-blocked": true, "x-rate-limit": { "limit": 60, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "identifier", "in": "path", "required": true, "description": "Enterprise number or VAT number of the company to look up.", "schema": { "type": "string" }, "example": "0477472701" }, { "name": "country", "in": "query", "schema": { "type": "string" } }, { "name": "refresh", "in": "query", "description": "Ignore the cache.", "schema": { "type": "boolean" } }, { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySheet" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/lookup/vat": { "get": { "operationId": "lookup.vat", "tags": [ "Lookup" ], "summary": "Check a VAT number", "description": "Format, check digits and existence, with the Peppol status when known.\n\nIntegration tokens need the `read` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 60 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.lookup.vat", "x-required-ability": "read", "x-demo-blocked": true, "x-rate-limit": { "limit": 60, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "vat", "in": "query", "required": true, "schema": { "type": "string" }, "example": "BE0477472701" }, { "name": "country", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ] }, "valid_format": { "type": "boolean" }, "vat_number": { "type": "string" }, "enterprise_number": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "address_line": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "peppol": { "type": [ "object", "null" ], "additionalProperties": true }, "reason": { "type": [ "string", "null" ] }, "source": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/lookup/cities": { "get": { "operationId": "lookup.cities", "tags": [ "Lookup" ], "summary": "City autocompletion", "description": "Integration tokens need the `read` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 120 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.lookup.cities", "x-required-ability": "read", "x-demo-blocked": true, "x-rate-limit": { "limit": 120, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "example": "Mons" }, { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "BE" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "postal_code": { "type": "string", "example": "7000" }, "city": { "type": "string", "example": "Mons" }, "city_fr": { "type": [ "string", "null" ] }, "city_nl": { "type": [ "string", "null" ], "example": "Bergen" }, "country": { "type": "string", "example": "BE" } } } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/lookup/streets": { "get": { "operationId": "lookup.streets", "tags": [ "Lookup" ], "summary": "Street autocompletion", "description": "Integration tokens need the `read` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 120 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.lookup.streets", "x-required-ability": "read", "x-demo-blocked": true, "x-rate-limit": { "limit": 120, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "zipcode", "in": "query", "required": true, "description": "Four digits.", "schema": { "type": "string" }, "example": "7000" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "example": "Grand" }, { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "BE" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "street": { "type": "string", "example": "Grand-Place" }, "street_fr": { "type": [ "string", "null" ] }, "street_nl": { "type": [ "string", "null" ] }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } } } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/companies/{company}/lookup/capabilities": { "get": { "operationId": "companies.lookup.capabilities", "tags": [ "Lookup" ], "summary": "Lookup capabilities of a country", "description": "What the detection can do for a country: BE and FR through CompanySearch (search, sheet, cities, streets), other EU countries through VIES (VAT check only). The call is attributed to the company file.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.lookup.capabilities", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "BE" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string", "example": "BE" }, "search": { "type": "boolean" }, "sheet": { "type": "boolean" }, "vat": { "type": "boolean" }, "cities": { "type": "boolean" }, "streets": { "type": "boolean" }, "source": { "type": "string", "example": "companysearch" }, "provider_configured": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/lookup/search": { "get": { "operationId": "companies.lookup.search", "tags": [ "Lookup" ], "summary": "Search a company by name or number", "description": "The call is attributed to the company file.\n\nIntegration tokens need the `read` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 60 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.lookup.search", "x-required-ability": "read", "x-demo-blocked": true, "x-rate-limit": { "limit": 60, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "q", "in": "query", "required": true, "description": "2 characters at least.", "schema": { "type": "string" }, "example": "comptoir montois" }, { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "BE" }, { "name": "limit", "in": "query", "description": "1 to 25.", "schema": { "type": "integer" } }, { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string", "example": "0477472701" }, "name": { "type": "string", "example": "Le Comptoir Montois" }, "legal_form": { "type": [ "string", "null" ], "example": "SRL" }, "vat_number": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ], "example": "7000" }, "city": { "type": [ "string", "null" ], "example": "Mons" }, "status": { "type": [ "string", "null" ], "example": "active" } } } }, "search_supported": { "type": "boolean" }, "provider_configured": { "type": "boolean" }, "source": { "type": "string" }, "country": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/companies/{company}/lookup/companies/{identifier}": { "get": { "operationId": "companies.lookup.companies.show", "tags": [ "Lookup" ], "summary": "Company sheet", "description": "Normalised sheet of a company, cached 24 hours. The call is attributed to the company file.\n\nIntegration tokens need the `read` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 60 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.lookup.companies.show", "x-required-ability": "read", "x-demo-blocked": true, "x-rate-limit": { "limit": 60, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "identifier", "in": "path", "required": true, "description": "Enterprise number or VAT number of the company to look up.", "schema": { "type": "string" }, "example": "0477472701" }, { "name": "country", "in": "query", "schema": { "type": "string" } }, { "name": "refresh", "in": "query", "description": "Ignore the cache.", "schema": { "type": "boolean" } }, { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySheet" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/companies/{company}/lookup/vat": { "get": { "operationId": "companies.lookup.vat", "tags": [ "Lookup" ], "summary": "Check a VAT number", "description": "Format, check digits and existence, with the Peppol status when known. The call is attributed to the company file.\n\nIntegration tokens need the `read` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 60 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.lookup.vat", "x-required-ability": "read", "x-demo-blocked": true, "x-rate-limit": { "limit": 60, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "vat", "in": "query", "required": true, "schema": { "type": "string" }, "example": "BE0477472701" }, { "name": "country", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ] }, "valid_format": { "type": "boolean" }, "vat_number": { "type": "string" }, "enterprise_number": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "address_line": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "peppol": { "type": [ "object", "null" ], "additionalProperties": true }, "reason": { "type": [ "string", "null" ] }, "source": { "type": "string" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/companies/{company}/lookup/cities": { "get": { "operationId": "companies.lookup.cities", "tags": [ "Lookup" ], "summary": "City autocompletion", "description": "The call is attributed to the company file.\n\nIntegration tokens need the `read` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 120 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.lookup.cities", "x-required-ability": "read", "x-demo-blocked": true, "x-rate-limit": { "limit": 120, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "example": "Mons" }, { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "BE" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "postal_code": { "type": "string", "example": "7000" }, "city": { "type": "string", "example": "Mons" }, "city_fr": { "type": [ "string", "null" ] }, "city_nl": { "type": [ "string", "null" ], "example": "Bergen" }, "country": { "type": "string", "example": "BE" } } } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/companies/{company}/lookup/streets": { "get": { "operationId": "companies.lookup.streets", "tags": [ "Lookup" ], "summary": "Street autocompletion", "description": "The call is attributed to the company file.\n\nIntegration tokens need the `read` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 120 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.lookup.streets", "x-required-ability": "read", "x-demo-blocked": true, "x-rate-limit": { "limit": 120, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "zipcode", "in": "query", "required": true, "description": "Four digits.", "schema": { "type": "string" }, "example": "7000" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "example": "Grand" }, { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "BE" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "street": { "type": "string", "example": "Grand-Place" }, "street_fr": { "type": [ "string", "null" ] }, "street_nl": { "type": [ "string", "null" ] }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } } } } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/companies/{company}/accounts": { "get": { "operationId": "companies.accounts.index", "tags": [ "Chart of accounts" ], "summary": "Chart of accounts", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.accounts.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "q", "in": "query", "description": "Number prefix or part of the label.", "schema": { "type": "string" }, "example": "6120" }, { "name": "postable", "in": "query", "description": "Only the accounts entries can be posted to.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "companies.accounts.store", "tags": [ "Chart of accounts" ], "summary": "Create an account", "description": "Integration tokens need the `write` ability.", "x-route-name": "api.v1.companies.accounts.store", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "string", "description": "2 to 12 digits, unique in the file." }, "type": { "type": "string", "enum": [ "asset", "liability", "expense", "income", "off_balance" ] }, "label": { "type": "string", "description": "200 characters max." }, "is_postable": { "type": "boolean" }, "is_reconcilable": { "type": "boolean" }, "purchase_grid": { "type": [ "integer", "null" ], "description": "81, 82 or 83." }, "default_vat_code_id": { "type": [ "integer", "null" ] } }, "required": [ "number", "type", "label" ] }, "example": { "number": "612100", "label": "Électricité", "type": "expense", "is_postable": true, "purchase_grid": 82 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/accounts/{account}": { "patch": { "operationId": "companies.accounts.update", "tags": [ "Chart of accounts" ], "summary": "Update an account", "description": "The number and the type of an account never change.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.accounts.update", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "account", "in": "path", "required": true, "description": "Id of the account (not its number).", "schema": { "type": "integer" }, "example": 223 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "200 characters max." }, "is_postable": { "type": "boolean" }, "is_reconcilable": { "type": "boolean" }, "purchase_grid": { "type": [ "integer", "null" ], "description": "81, 82 or 83." }, "default_vat_code_id": { "type": [ "integer", "null" ] } } }, "example": { "label": "Électricité et gaz" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/journals": { "get": { "operationId": "companies.journals.index", "tags": [ "Journals" ], "summary": "Journals", "description": "With their control account, routing rules and number of entries.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.journals.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Journal" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "companies.journals.store", "tags": [ "Journals" ], "summary": "Create a journal", "description": "Integration tokens need the `write` ability.", "x-route-name": "api.v1.companies.journals.store", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Letters and digits, 6 max, unique." }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "purchase", "sale", "purchase_credit_note", "sale_credit_note", "financial", "miscellaneous" ] }, "control_account_id": { "type": [ "integer", "null" ] }, "iban": { "type": [ "string", "null" ] }, "bic": { "type": [ "string", "null" ] } }, "required": [ "code", "label", "type" ] }, "example": { "code": "ING", "label": "ING Business", "type": "financial", "iban": "BE12310123456789" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Journal" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/journals/{journal}": { "patch": { "operationId": "companies.journals.update", "tags": [ "Journals" ], "summary": "Update a journal", "description": "`is_default` makes it the default journal of its type.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.journals.update", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "journal", "in": "path", "required": true, "description": "Id of the journal.", "schema": { "type": "integer" }, "example": 3 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "control_account_id": { "type": [ "integer", "null" ] }, "iban": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "is_default": { "type": "boolean" } } }, "example": { "is_default": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Journal" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "operationId": "companies.journals.destroy", "tags": [ "Journals" ], "summary": "Delete a journal", "description": "Only a journal that never held an entry (continuous numbering); otherwise deactivate it. Goes to the recycle bin.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.journals.destroy", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "journal", "in": "path", "required": true, "description": "Id of the journal.", "schema": { "type": "integer" }, "example": 3 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "responses": { "204": { "description": "Done, no body.", "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-Trashed": { "$ref": "#/components/headers/X-Trashed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/journal-rules": { "get": { "operationId": "companies.journal-rules.index", "tags": [ "Journals" ], "summary": "Journal routing rules", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.journal-rules.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JournalRule" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "companies.journal-rules.store", "tags": [ "Journals" ], "summary": "Create a journal rule", "description": "Integration tokens need the `write` ability.", "x-route-name": "api.v1.companies.journal-rules.store", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "journal_id": { "type": "integer" }, "direction": { "type": "string", "enum": [ "sale", "purchase" ] }, "match_field": { "type": "string", "enum": [ "payment_provider", "number_series", "number_prefix", "third_party" ] }, "match_value": { "type": "string", "description": "100 characters max." }, "priority": { "type": "integer", "description": "1 to 999, lowest first." }, "is_active": { "type": "boolean" } }, "required": [ "journal_id", "direction", "match_field", "match_value" ] }, "example": { "journal_id": 3, "direction": "sale", "match_field": "number_prefix", "match_value": "TK" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalRule" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/journal-rules/{journalRule}": { "patch": { "operationId": "companies.journal-rules.update", "tags": [ "Journals" ], "summary": "Update a journal rule", "description": "Integration tokens need the `write` ability.", "x-route-name": "api.v1.companies.journal-rules.update", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "journalRule", "in": "path", "required": true, "description": "Id of the journal rule.", "schema": { "type": "integer" }, "example": 4 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "journal_id": { "type": "integer" }, "direction": { "type": "string", "enum": [ "sale", "purchase" ] }, "match_field": { "type": "string", "enum": [ "payment_provider", "number_series", "number_prefix", "third_party" ] }, "match_value": { "type": "string", "description": "100 characters max." }, "priority": { "type": "integer", "description": "1 to 999, lowest first." }, "is_active": { "type": "boolean" } } }, "example": { "priority": 10 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalRule" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "operationId": "companies.journal-rules.destroy", "tags": [ "Journals" ], "summary": "Delete a journal rule", "description": "Integration tokens need the `write` ability.", "x-route-name": "api.v1.companies.journal-rules.destroy", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "journalRule", "in": "path", "required": true, "description": "Id of the journal rule.", "schema": { "type": "integer" }, "example": 4 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "responses": { "204": { "description": "Done, no body.", "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-Trashed": { "$ref": "#/components/headers/X-Trashed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/companies/{company}/documents/series": { "get": { "operationId": "companies.documents.series", "tags": [ "Journals" ], "summary": "Numbering series of the documents", "description": "Series observed in the imported documents (prefix and payment provider) and the journal resolved for each.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.documents.series", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "sale", "purchase" ] }, "is_credit_note": { "type": "boolean" }, "number_series": { "type": [ "string", "null" ], "example": "TK" }, "payment_provider": { "type": [ "string", "null" ] }, "documents": { "type": "integer", "example": 214 }, "pending": { "type": "integer", "example": 6 }, "sample_number": { "type": [ "string", "null" ], "example": "TK-2026-00214" }, "journal": { "type": [ "object", "null" ], "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/fiscal-years": { "get": { "operationId": "companies.fiscal-years.index", "tags": [ "Fiscal years" ], "summary": "Fiscal years and periods", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.fiscal-years.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalYear" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "companies.fiscal-years.store", "tags": [ "Fiscal years" ], "summary": "Open a fiscal year", "description": "Creates the year and its periods (opening, one per month, closing).\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.fiscal-years.store", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Unique, 10 characters max." }, "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" } }, "required": [ "code", "starts_on", "ends_on" ] }, "example": { "code": "2027", "starts_on": "2027-01-01", "ends_on": "2027-12-31" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalYear" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/fiscal-years/{fiscalYear}/periods/{period}": { "patch": { "operationId": "companies.fiscal-years.periods.update", "tags": [ "Fiscal years" ], "summary": "Lock or unlock a period", "description": "No entry can be posted in a locked period. Refused with `period_locked` (reason `fiscal_year_closed`) when the fiscal year is closed.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `period_locked`: the period is locked or the fiscal year is closed; `reason` tells which (`period_locked` or `fiscal_year_closed`)", "x-route-name": "api.v1.companies.fiscal-years.periods.update", "x-required-ability": "write", "x-error-codes": [ "period_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "name": "period", "in": "path", "required": true, "description": "Id of the period.", "schema": { "type": "integer" }, "example": 16 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "is_locked": { "type": "boolean" } }, "required": [ "is_locked" ] }, "example": { "is_locked": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Period" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/PeriodLockedOrValidationError" } } } }, "/v1/companies/{company}/fiscal-years/{fiscalYear}/close": { "post": { "operationId": "companies.fiscal-years.close", "tags": [ "Fiscal years" ], "summary": "Close or reopen a fiscal year", "description": "Locks every period. Send `reopen: true` to reopen. For the closing entries and the carry-forward use `year-end`.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.fiscal-years.close", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reopen": { "type": "boolean" } } }, "example": { "reopen": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalYear" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/fiscal-years/{fiscalYear}/year-end": { "post": { "operationId": "companies.fiscal-years.year-end", "tags": [ "Fiscal years" ], "summary": "Year-end closing", "description": "Posts the closing entry (result), opens the next fiscal year when needed, posts the opening entry (carry-forward of the balance sheet accounts) and closes the year. Emits the webhook `fiscal_year.closed`.\n\nIntegration tokens need the `write` ability.\n\nRate limit: 5 requests per minute (429 beyond, see `Retry-After`).\n\nError codes (`code`):\n- `period_locked`: the period is locked or the fiscal year is closed; `reason` tells which (`period_locked` or `fiscal_year_closed`)", "x-route-name": "api.v1.companies.fiscal-years.year-end", "x-required-ability": "write", "x-rate-limit": { "limit": 5, "window_minutes": 1 }, "x-error-codes": [ "period_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "18420.11", "description": "Result of the year." }, "closing_entry": { "anyOf": [ { "$ref": "#/components/schemas/JournalEntry" }, { "type": "null" } ] }, "opening_entry": { "anyOf": [ { "$ref": "#/components/schemas/JournalEntry" }, { "type": "null" } ] }, "fiscal_year": { "$ref": "#/components/schemas/FiscalYear" }, "next_fiscal_year": { "$ref": "#/components/schemas/FiscalYear" } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/PeriodLockedOrValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/third-parties": { "get": { "operationId": "companies.third-parties.index", "tags": [ "Third parties" ], "summary": "List the third parties", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.third-parties.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "customer", "supplier" ] } }, { "name": "q", "in": "query", "description": "Name, code or VAT number.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ThirdParty" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "companies.third-parties.store", "tags": [ "Third parties" ], "summary": "Create a third party", "description": "Integration tokens need the `write` ability.", "x-route-name": "api.v1.companies.third-parties.store", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "customer", "supplier" ] }, "code": { "type": [ "string", "null" ], "description": "Unique per type; generated from the name when absent." }, "name": { "type": "string" }, "contact_name": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ], "description": "Validated per country." }, "enterprise_number": { "type": [ "string", "null" ] }, "legal_form_code": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "box": { "type": [ "string", "null" ] }, "nace_code": { "type": [ "string", "null" ] }, "vat_status": { "type": "string", "enum": [ "subject", "not_subject", "exempt", "intra_eu", "non_eu" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2, BE by default." }, "language": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] }, "category": { "type": [ "string", "null" ] }, "currency": { "type": "string", "description": "ISO 4217." }, "address": { "type": [ "string", "null" ] }, "address_line_2": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "iban": { "type": [ "string", "null" ] }, "bic": { "type": [ "string", "null" ] }, "bank_account": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "fax": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "payment_terms_days": { "type": "integer", "description": "0 to 365." }, "form_281_50_type": { "type": [ "string", "null" ] }, "profession_281_50": { "type": [ "string", "null" ] }, "is_natural_person": { "type": "boolean" }, "notes": { "type": [ "string", "null" ] }, "default_vat_code_id": { "type": [ "integer", "null" ] }, "default_account_id": { "type": [ "integer", "null" ] } }, "required": [ "type", "name" ] }, "example": { "type": "supplier", "name": "Brasserie Dubuisson SA", "vat_number": "BE 0402.531.376", "address": "Chaussée de Mons 28", "postal_code": "7904", "city": "Pipaix", "iban": "BE71 0961 2345 6769", "payment_terms_days": 30 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThirdParty" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/third-parties/{thirdParty}": { "get": { "operationId": "companies.third-parties.show", "tags": [ "Third parties" ], "summary": "Third party sheet", "description": "With its default account and VAT code.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.third-parties.show", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "thirdParty", "in": "path", "required": true, "description": "Id of the third party.", "schema": { "type": "integer" }, "example": 18 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThirdParty" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "companies.third-parties.update", "tags": [ "Third parties" ], "summary": "Update a third party", "description": "Integration tokens need the `write` ability.", "x-route-name": "api.v1.companies.third-parties.update", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "thirdParty", "in": "path", "required": true, "description": "Id of the third party.", "schema": { "type": "integer" }, "example": 18 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Unique per type; generated from the name when absent." }, "name": { "type": "string" }, "contact_name": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ], "description": "Validated per country." }, "enterprise_number": { "type": [ "string", "null" ] }, "legal_form_code": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "box": { "type": [ "string", "null" ] }, "nace_code": { "type": [ "string", "null" ] }, "vat_status": { "type": "string", "enum": [ "subject", "not_subject", "exempt", "intra_eu", "non_eu" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2, BE by default." }, "language": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] }, "category": { "type": [ "string", "null" ] }, "currency": { "type": "string", "description": "ISO 4217." }, "address": { "type": [ "string", "null" ] }, "address_line_2": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "iban": { "type": [ "string", "null" ] }, "bic": { "type": [ "string", "null" ] }, "bank_account": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "fax": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "payment_terms_days": { "type": "integer", "description": "0 to 365." }, "form_281_50_type": { "type": [ "string", "null" ] }, "profession_281_50": { "type": [ "string", "null" ] }, "is_natural_person": { "type": "boolean" }, "notes": { "type": [ "string", "null" ] }, "default_vat_code_id": { "type": [ "integer", "null" ] }, "default_account_id": { "type": [ "integer", "null" ] } } }, "example": { "payment_terms_days": 45, "email": "compta@dubuisson.example" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThirdParty" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "operationId": "companies.third-parties.destroy", "tags": [ "Third parties" ], "summary": "Delete a third party", "description": "Refused (422) when an entry or a document references it. Goes to the recycle bin.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.third-parties.destroy", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "thirdParty", "in": "path", "required": true, "description": "Id of the third party.", "schema": { "type": "integer" }, "example": 18 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "responses": { "204": { "description": "Done, no body.", "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-Trashed": { "$ref": "#/components/headers/X-Trashed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/third-parties/{thirdParty}/entries": { "get": { "operationId": "companies.third-parties.entries", "tags": [ "Third parties" ], "summary": "Open items and entries of a third party", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.third-parties.entries", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "thirdParty", "in": "path", "required": true, "description": "Id of the third party.", "schema": { "type": "integer" }, "example": 18 }, { "name": "lettered", "in": "query", "schema": { "type": "string", "enum": [ "all", "yes", "no" ] } }, { "name": "fiscal_year_id", "in": "query", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "line_id": { "type": "integer", "example": 3391 }, "entry_id": { "type": "integer", "example": 1284 }, "journal_code": { "type": "string", "example": "VEN" }, "entry_number": { "type": "integer", "example": 412 }, "document_number": { "type": [ "string", "null" ], "example": "2026/0412" }, "period_number": { "type": "integer", "example": 3 }, "entry_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1210.00" }, "debit": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1210.00" }, "credit": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "reconciliation_code": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "reminder_level": { "type": "integer", "example": 0 }, "reminder_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "is_lettered": { "type": "boolean", "example": false } } } }, "summary": { "type": "object", "properties": { "balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1210.00" }, "open_count": { "type": "integer", "example": 1 }, "lettered_count": { "type": "integer", "example": 0 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/third-parties/{thirdParty}/letter": { "post": { "operationId": "companies.third-parties.letter", "tags": [ "Third parties" ], "summary": "Letter lines together", "description": "Matches lines of the third party whose debits and credits balance (a small difference is posted to the difference accounts of the settings).\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.third-parties.letter", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "thirdParty", "in": "path", "required": true, "description": "Id of the third party.", "schema": { "type": "integer" }, "example": 18 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "line_ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "line_ids" ] }, "example": { "line_ids": [ 3391, 3518 ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "AB", "description": "Lettering code given." }, "line_ids": { "type": "array", "items": { "type": "integer" } } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/third-parties/{thirdParty}/unletter": { "post": { "operationId": "companies.third-parties.unletter", "tags": [ "Third parties" ], "summary": "Remove a lettering", "description": "By lettering code or by lines.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.third-parties.unletter", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "thirdParty", "in": "path", "required": true, "description": "Id of the third party.", "schema": { "type": "integer" }, "example": 18 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "line_ids": { "type": "array", "items": { "type": "integer" } } } }, "example": { "code": "AB" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string", "example": "AB", "description": "Lettering code removed." } }, "line_ids": { "type": "array", "items": { "type": "integer" } } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/third-parties/{thirdParty}/letter-auto": { "post": { "operationId": "companies.third-parties.letter-auto", "tags": [ "Third parties" ], "summary": "Automatic lettering", "description": "Letters every group of open lines that balances exactly.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.third-parties.letter-auto", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "thirdParty", "in": "path", "required": true, "description": "Id of the third party.", "schema": { "type": "integer" }, "example": 18 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "integer", "example": 3 }, "line_ids": { "type": "array", "items": { "type": "integer" } } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/third-parties/{thirdParty}/entries/{line}/remind": { "post": { "operationId": "companies.third-parties.remind", "tags": [ "Third parties" ], "summary": "Record a payment reminder", "description": "Raises the reminder level of an open line and stamps the date. No e-mail is sent by this endpoint.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.", "x-route-name": "api.v1.companies.third-parties.remind", "x-required-ability": "write", "x-demo-blocked": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "thirdParty", "in": "path", "required": true, "description": "Id of the third party.", "schema": { "type": "integer" }, "example": 18 }, { "name": "line", "in": "path", "required": true, "description": "Id of the line.", "schema": { "type": "integer" }, "example": 3391 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "description": "The row, as in the entries list." } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/third-parties/{thirdParty}/reminders": { "get": { "operationId": "companies.third-parties.reminders", "tags": [ "Third parties" ], "summary": "Reminders of a third party", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.third-parties.reminders", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "thirdParty", "in": "path", "required": true, "description": "Id of the third party.", "schema": { "type": "integer" }, "example": 18 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/third-parties/{thirdParty}/totals": { "get": { "operationId": "companies.third-parties.totals", "tags": [ "Third parties" ], "summary": "Totals per period", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.third-parties.totals", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "thirdParty", "in": "path", "required": true, "description": "Id of the third party.", "schema": { "type": "integer" }, "example": 18 }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "balance", "debit", "credit" ] } }, { "name": "fiscal_year_id", "in": "query", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "fiscal_year": { "type": "object", "properties": { "id": { "type": "integer" }, "code": { "type": "string", "example": "2026" } } }, "mode": { "type": "string", "example": "balance" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "period_number": { "type": "integer", "example": 1 }, "period_label": { "type": "string", "example": "Janvier 2026" }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } } }, "total": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/vies": { "get": { "operationId": "companies.vies.check", "tags": [ "Third parties" ], "summary": "Check a VAT number with VIES", "description": "Integration tokens need the `read` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 30 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.vies.check", "x-required-ability": "read", "x-demo-blocked": true, "x-rate-limit": { "limit": 30, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "vat_number", "in": "query", "required": true, "schema": { "type": "string" }, "example": "BE0402531376" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ], "description": "Null when VIES did not answer." }, "name": { "type": [ "string", "null" ], "example": "BRASSERIE DUBUISSON" }, "address": { "type": [ "string", "null" ] }, "country": { "type": "string", "example": "BE" }, "number": { "type": "string", "example": "0402531376" }, "error": { "type": [ "string", "null" ], "description": "invalid_format, service_unavailable or the VIES user error." } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/third-parties/{thirdParty}/vies": { "post": { "operationId": "companies.third-parties.vies", "tags": [ "Third parties" ], "summary": "Check the VAT number of a third party with VIES", "description": "Stores the result on the third party (`vies_valid`, `vies_checked_at`, `vies_name`).\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 30 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.third-parties.vies", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 30, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "thirdParty", "in": "path", "required": true, "description": "Id of the third party.", "schema": { "type": "integer" }, "example": 18 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": [ "boolean", "null" ], "description": "Null when VIES did not answer." }, "name": { "type": [ "string", "null" ], "example": "BRASSERIE DUBUISSON" }, "address": { "type": [ "string", "null" ] }, "country": { "type": "string", "example": "BE" }, "number": { "type": "string", "example": "0402531376" }, "error": { "type": [ "string", "null" ], "description": "invalid_format, service_unavailable or the VIES user error." }, "third_party": { "$ref": "#/components/schemas/ThirdParty" } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/entries": { "get": { "operationId": "companies.entries.index", "tags": [ "Entries" ], "summary": "List the entries", "description": "Newest first, with their journal, third party and lines.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.entries.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "journal_id", "in": "query", "schema": { "type": "integer" } }, { "name": "fiscal_year_id", "in": "query", "schema": { "type": "integer" } }, { "name": "third_party_id", "in": "query", "schema": { "type": "integer" } }, { "name": "from", "in": "query", "description": "Entry date, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Entry date, inclusive.", "schema": { "type": "string", "format": "date" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "posted", "reversed" ] } }, { "name": "q", "in": "query", "description": "Label, reference, structured communication, third party name, line label or account number prefix.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntry" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "companies.entries.store", "tags": [ "Entries" ], "summary": "Post a free entry", "description": "Miscellaneous operation, financial entry…: every line is given, debits must equal credits. The entry is posted at once and numbered in its journal. Accounts are addressed by `account_id` or by number (`account`). A date in a locked period or a closed fiscal year is refused with 422 `period_locked`.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `period_locked`: the period is locked or the fiscal year is closed; `reason` tells which (`period_locked` or `fiscal_year_closed`)", "x-route-name": "api.v1.companies.entries.store", "x-required-ability": "write", "x-error-codes": [ "period_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "journal_id": { "type": "integer" }, "entry_date": { "type": "string", "format": "date", "description": "Inside an open fiscal year and an unlocked period." }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "label": { "type": "string", "description": "200 characters max." }, "reference": { "type": [ "string", "null" ], "description": "60 characters max." }, "structured_communication": { "type": [ "string", "null" ], "description": "Belgian structured communication." }, "third_party_id": { "type": [ "integer", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "integer", "description": "Required without `account`." }, "account": { "type": "string", "description": "Account number; required without `account_id`." }, "debit": { "type": [ "string", "null" ], "description": "Decimal, positive." }, "credit": { "type": [ "string", "null" ], "description": "Decimal, positive." }, "label": { "type": [ "string", "null" ] }, "third_party_id": { "type": [ "integer", "null" ] }, "vat_code_id": { "type": [ "integer", "null" ] }, "vat_base": { "type": [ "string", "null" ], "description": "Taxable base carried by the line." }, "cost_center_id": { "type": [ "integer", "null" ], "description": "Analytic code of the `cost_center` axis." }, "project_id": { "type": [ "integer", "null" ], "description": "Analytic code of the `project` axis." } } } } }, "required": [ "journal_id", "entry_date", "label", "lines" ] }, "example": { "journal_id": 5, "entry_date": "2026-03-31", "label": "Salaires mars 2026", "reference": "SAL-2026-03", "lines": [ { "account": "620200", "debit": "8420.00", "label": "Rémunérations brutes" }, { "account": "453000", "credit": "2105.00", "label": "Précompte professionnel" }, { "account": "454000", "credit": "1100.48", "label": "ONSS" }, { "account": "455000", "credit": "5214.52", "label": "Net à payer" } ] } } } }, "responses": { "201": { "description": "Entry posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalEntry" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/PeriodLockedOrValidationError" } } } }, "/v1/companies/{company}/entries/invoice": { "post": { "operationId": "companies.entries.invoice", "tags": [ "Entries" ], "summary": "Post an invoice or a credit note", "description": "Purchase or sale invoice (journal of type purchase / sale) or credit note (journal of type purchase_credit_note / sale_credit_note). Send the net lines with their VAT code: the VAT lines and the third party line are generated, including reverse charge (intra-EU, co-contractor). The label defaults to « Facture ». A date in a locked period or a closed fiscal year is refused with 422 `period_locked`.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `period_locked`: the period is locked or the fiscal year is closed; `reason` tells which (`period_locked` or `fiscal_year_closed`)", "x-route-name": "api.v1.companies.entries.invoice", "x-required-ability": "write", "x-error-codes": [ "period_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "journal_id": { "type": "integer", "description": "Journal of a purchase or sale type." }, "third_party_id": { "type": "integer" }, "entry_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "label": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ], "description": "Invoice number." }, "structured_communication": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "integer", "description": "Required without `account`." }, "account": { "type": "string", "description": "Account number." }, "amount": { "type": "string", "description": "Net amount (excl. VAT), decimal." }, "vat_code_id": { "type": [ "integer", "null" ] }, "vat_code": { "type": [ "string", "null" ], "description": "Code of the VAT code (`V21`, `A06`, `AIC21`…)." }, "label": { "type": [ "string", "null" ] }, "cost_center_id": { "type": [ "integer", "null" ], "description": "Analytic code of the `cost_center` axis." }, "project_id": { "type": [ "integer", "null" ], "description": "Analytic code of the `project` axis." } }, "required": [ "amount" ] } } }, "required": [ "journal_id", "third_party_id", "entry_date", "lines" ] }, "example": { "journal_id": 1, "third_party_id": 18, "entry_date": "2026-03-15", "due_date": "2026-04-14", "reference": "F-2026-0412", "lines": [ { "account": "604000", "amount": "507.00", "vat_code": "A21", "label": "Fûts Bush Caractère 20 L" }, { "account": "613200", "amount": "35.00", "vat_code": "A21", "label": "Consigne et transport" } ] } } } }, "responses": { "201": { "description": "Invoice posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalEntry" }, "example": { "id": 1284, "company_id": 7, "fiscal_year_id": 2, "period_id": 16, "journal_id": 1, "number": 412, "entry_date": "2026-03-15T00:00:00.000000Z", "due_date": "2026-04-14T00:00:00.000000Z", "label": "Facture Brasserie Dubuisson SA", "reference": "F-2026-0412", "structured_communication": null, "third_party_id": 18, "status": "posted", "origin": "manual", "created_by": 12, "posted_at": "2026-03-16T08:12:40.000000Z", "reversed_entry_id": null, "reversed_by_entry_id": null, "recurring_entry_id": null, "created_at": "2026-03-16T08:12:40.000000Z", "updated_at": "2026-03-16T08:12:40.000000Z", "lock_version": 1, "version": 1, "lines": [ { "id": 3391, "journal_entry_id": 1284, "position": 1, "account_id": 361, "third_party_id": null, "label": "Fûts Bush Caractère 20 L", "debit": "507.00", "credit": "0.00", "vat_code_id": 25, "vat_base": "507.00", "reconciliation_code": null, "cost_center_id": null, "project_id": null, "reminder_level": 0, "reminder_sent_at": null, "account": { "id": 361, "number": "604000", "label": "Achats de marchandises" } }, { "id": 3392, "journal_entry_id": 1284, "position": 2, "account_id": 384, "third_party_id": null, "label": "Consigne et transport", "debit": "35.00", "credit": "0.00", "vat_code_id": 25, "vat_base": "35.00", "reconciliation_code": null, "cost_center_id": null, "project_id": null, "reminder_level": 0, "reminder_sent_at": null, "account": { "id": 384, "number": "613200", "label": "Transports et déplacements" } }, { "id": 3393, "journal_entry_id": 1284, "position": 3, "account_id": 234, "third_party_id": null, "label": "TVA déductible", "debit": "113.82", "credit": "0.00", "vat_code_id": null, "vat_base": null, "reconciliation_code": null, "cost_center_id": null, "project_id": null, "reminder_level": 0, "reminder_sent_at": null, "account": { "id": 234, "number": "411100", "label": "TVA déductible sur achats" } }, { "id": 3394, "journal_entry_id": 1284, "position": 4, "account_id": 263, "third_party_id": 18, "label": "Brasserie Dubuisson SA", "debit": "0.00", "credit": "655.82", "vat_code_id": null, "vat_base": null, "reconciliation_code": null, "cost_center_id": null, "project_id": null, "reminder_level": 0, "reminder_sent_at": null, "account": { "id": 263, "number": "440000", "label": "Fournisseurs" } } ] } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/PeriodLockedOrValidationError" } } } }, "/v1/companies/{company}/entries/{journalEntry}": { "get": { "operationId": "companies.entries.show", "tags": [ "Entries" ], "summary": "Entry", "description": "With journal, third party, fiscal year, period and lines (account and VAT code).\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.entries.show", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "journalEntry", "in": "path", "required": true, "description": "Id of the journal entry.", "schema": { "type": "integer" }, "example": 1284 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalEntry" }, "example": { "id": 1284, "company_id": 7, "fiscal_year_id": 2, "period_id": 16, "journal_id": 1, "number": 412, "entry_date": "2026-03-15T00:00:00.000000Z", "due_date": "2026-04-14T00:00:00.000000Z", "label": "Facture Brasserie Dubuisson SA", "reference": "F-2026-0412", "structured_communication": null, "third_party_id": 18, "status": "posted", "origin": "manual", "created_by": 12, "posted_at": "2026-03-16T08:12:40.000000Z", "reversed_entry_id": null, "reversed_by_entry_id": null, "recurring_entry_id": null, "created_at": "2026-03-16T08:12:40.000000Z", "updated_at": "2026-03-16T08:12:40.000000Z", "lock_version": 1, "version": 1, "lines": [ { "id": 3391, "journal_entry_id": 1284, "position": 1, "account_id": 361, "third_party_id": null, "label": "Fûts Bush Caractère 20 L", "debit": "507.00", "credit": "0.00", "vat_code_id": 25, "vat_base": "507.00", "reconciliation_code": null, "cost_center_id": null, "project_id": null, "reminder_level": 0, "reminder_sent_at": null, "account": { "id": 361, "number": "604000", "label": "Achats de marchandises" } }, { "id": 3392, "journal_entry_id": 1284, "position": 2, "account_id": 384, "third_party_id": null, "label": "Consigne et transport", "debit": "35.00", "credit": "0.00", "vat_code_id": 25, "vat_base": "35.00", "reconciliation_code": null, "cost_center_id": null, "project_id": null, "reminder_level": 0, "reminder_sent_at": null, "account": { "id": 384, "number": "613200", "label": "Transports et déplacements" } }, { "id": 3393, "journal_entry_id": 1284, "position": 3, "account_id": 234, "third_party_id": null, "label": "TVA déductible", "debit": "113.82", "credit": "0.00", "vat_code_id": null, "vat_base": null, "reconciliation_code": null, "cost_center_id": null, "project_id": null, "reminder_level": 0, "reminder_sent_at": null, "account": { "id": 234, "number": "411100", "label": "TVA déductible sur achats" } }, { "id": 3394, "journal_entry_id": 1284, "position": 4, "account_id": 263, "third_party_id": 18, "label": "Brasserie Dubuisson SA", "debit": "0.00", "credit": "655.82", "vat_code_id": null, "vat_base": null, "reconciliation_code": null, "cost_center_id": null, "project_id": null, "reminder_level": 0, "reminder_sent_at": null, "account": { "id": 263, "number": "440000", "label": "Fournisseurs" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "companies.entries.destroy", "tags": [ "Entries" ], "summary": "Delete an entry", "description": "Always refused (422) for a posted entry: numbering is continuous and the audit trail is kept. Use `reverse`. In a locked period the refusal carries `period_locked`.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `period_locked`: the period is locked or the fiscal year is closed; `reason` tells which (`period_locked` or `fiscal_year_closed`)", "x-route-name": "api.v1.companies.entries.destroy", "x-required-ability": "write", "x-error-codes": [ "period_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "journalEntry", "in": "path", "required": true, "description": "Id of the journal entry.", "schema": { "type": "integer" }, "example": 1284 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "responses": { "204": { "description": "Done, no body.", "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-Trashed": { "$ref": "#/components/headers/X-Trashed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/PeriodLockedOrValidationError" } } } }, "/v1/companies/{company}/entries/{journalEntry}/reverse": { "post": { "operationId": "companies.entries.reverse", "tags": [ "Entries" ], "summary": "Reverse an entry", "description": "Posts the mirror entry (« Extourne de VEN 2026/000412 ») linked to the original, which becomes `reversed`. The linked document or bank transaction goes back to `pending`, letterings of the lines are removed and a depreciation line goes back to `planned`.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `period_locked`: the period is locked or the fiscal year is closed; `reason` tells which (`period_locked` or `fiscal_year_closed`)", "x-route-name": "api.v1.companies.entries.reverse", "x-required-ability": "write", "x-error-codes": [ "period_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "journalEntry", "in": "path", "required": true, "description": "Id of the journal entry.", "schema": { "type": "integer" }, "example": 1284 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "entry_date": { "type": [ "string", "null" ], "format": "date", "description": "Date of the reversal; the original date by default." }, "label": { "type": [ "string", "null" ] } } }, "example": { "entry_date": "2026-03-31" } } } }, "responses": { "201": { "description": "Reversal entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalEntry" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/PeriodLockedOrValidationError" } } } }, "/v1/companies/{company}/recurring-entries": { "get": { "operationId": "companies.recurring.index", "tags": [ "Recurring entries" ], "summary": "List the recurring entries", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.recurring.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringEntry" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "companies.recurring.store", "tags": [ "Recurring entries" ], "summary": "Create a recurring entry", "description": "Template posted automatically every night once `next_date` is reached (or on demand with `generate`).\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.recurring.store", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "journal_id": { "type": "integer" }, "label": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "third_party_id": { "type": [ "integer", "null" ] }, "frequency": { "type": "string", "enum": [ "monthly", "quarterly", "yearly" ] }, "next_date": { "type": "string", "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "is_active": { "type": "boolean" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "integer", "description": "Postable account." }, "debit": { "type": [ "string", "null" ], "description": "Decimal." }, "credit": { "type": [ "string", "null" ], "description": "Decimal." }, "label": { "type": [ "string", "null" ] }, "third_party_id": { "type": [ "integer", "null" ] } }, "required": [ "account_id" ] } } }, "required": [ "journal_id", "label", "frequency", "next_date", "lines" ] }, "example": { "journal_id": 5, "label": "Loyer mensuel", "frequency": "monthly", "next_date": "2026-04-01", "lines": [ { "account_id": 368, "debit": "1500.00" }, { "account_id": 263, "credit": "1500.00", "third_party_id": 22 } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringEntry" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/recurring-entries/generate": { "post": { "operationId": "companies.recurring.generate-all", "tags": [ "Recurring entries" ], "summary": "Generate every due entry", "description": "Integration tokens need the `write` ability.\n\nError codes (`code`):\n- `period_locked`: the period is locked or the fiscal year is closed; `reason` tells which (`period_locked` or `fiscal_year_closed`)", "x-route-name": "api.v1.companies.recurring.generate-all", "x-required-ability": "write", "x-error-codes": [ "period_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "generated": { "type": "integer", "example": 2 }, "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "reference": { "type": "string", "example": "OD 2026/000031" }, "entry_date": { "type": "string", "format": "date" } } } } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/PeriodLockedOrValidationError" } } } }, "/v1/companies/{company}/recurring-entries/{recurringEntry}": { "patch": { "operationId": "companies.recurring.update", "tags": [ "Recurring entries" ], "summary": "Update a recurring entry", "description": "Integration tokens need the `write` ability.", "x-route-name": "api.v1.companies.recurring.update", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "recurringEntry", "in": "path", "required": true, "description": "Id of the recurring entry template.", "schema": { "type": "integer" }, "example": 5 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "journal_id": { "type": "integer" }, "label": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "third_party_id": { "type": [ "integer", "null" ] }, "frequency": { "type": "string", "enum": [ "monthly", "quarterly", "yearly" ] }, "next_date": { "type": "string", "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "is_active": { "type": "boolean" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "integer", "description": "Postable account." }, "debit": { "type": [ "string", "null" ], "description": "Decimal." }, "credit": { "type": [ "string", "null" ], "description": "Decimal." }, "label": { "type": [ "string", "null" ] }, "third_party_id": { "type": [ "integer", "null" ] } }, "required": [ "account_id" ] } } } }, "example": { "is_active": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringEntry" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "operationId": "companies.recurring.destroy", "tags": [ "Recurring entries" ], "summary": "Delete a recurring entry", "description": "Integration tokens need the `write` ability.", "x-route-name": "api.v1.companies.recurring.destroy", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "recurringEntry", "in": "path", "required": true, "description": "Id of the recurring entry template.", "schema": { "type": "integer" }, "example": 5 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "responses": { "204": { "description": "Done, no body.", "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-Trashed": { "$ref": "#/components/headers/X-Trashed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/companies/{company}/recurring-entries/{recurringEntry}/generate": { "post": { "operationId": "companies.recurring.generate", "tags": [ "Recurring entries" ], "summary": "Generate the due entries of one template", "description": "Integration tokens need the `write` ability.\n\nError codes (`code`):\n- `period_locked`: the period is locked or the fiscal year is closed; `reason` tells which (`period_locked` or `fiscal_year_closed`)", "x-route-name": "api.v1.companies.recurring.generate", "x-required-ability": "write", "x-error-codes": [ "period_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "recurringEntry", "in": "path", "required": true, "description": "Id of the recurring entry template.", "schema": { "type": "integer" }, "example": 5 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "generated": { "type": "integer", "example": 1 }, "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "reference": { "type": "string", "example": "OD 2026/000031" }, "entry_date": { "type": "string", "format": "date" } } } } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/PeriodLockedOrValidationError" } } } }, "/v1/companies/{company}/quality": { "get": { "operationId": "companies.quality", "tags": [ "Recurring entries" ], "summary": "Quality checks", "description": "Continuous control of the file: documents and bank transactions pending, unbalanced entries, missing numbers, third parties without VAT number, VAT declarations late…\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.quality", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checked_at": { "type": "string", "format": "date-time" }, "score": { "type": "integer", "example": 8, "description": "Checks passed." }, "total": { "type": "integer", "example": 10 }, "checks": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "bank_pending" }, "severity": { "type": "string", "enum": [ "ok", "info", "warning", "error" ] }, "count": { "type": "integer", "example": 3 }, "detail": { "type": [ "object", "null" ], "additionalProperties": true } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/documents": { "get": { "operationId": "companies.documents.index", "tags": [ "Documents" ], "summary": "List the documents", "description": "Invoices, credit notes and receipts of the file (synchronised from Novadesko or created by the importer).\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.documents.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "sale", "purchase" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "booked", "ignored" ] } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "q", "in": "query", "description": "Number, third party or subject.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImportedDocument" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/documents/book-all": { "post": { "operationId": "companies.documents.book-all", "tags": [ "Documents" ], "summary": "Book every pending document", "description": "Books what can be booked; the others stay pending with the reason (a locked period is reported per document in `skipped_documents`).\n\nIntegration tokens need the `write` ability.\n\nRate limit: 5 requests per minute (429 beyond, see `Retry-After`).\n\nError codes (`code`):\n- `period_locked`: the period is locked or the fiscal year is closed; `reason` tells which (`period_locked` or `fiscal_year_closed`)", "x-route-name": "api.v1.companies.documents.book-all", "x-required-ability": "write", "x-rate-limit": { "limit": 5, "window_minutes": 1 }, "x-error-codes": [ "period_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "sale", "purchase" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "booked": { "type": "integer", "example": 42 }, "skipped": { "type": "integer", "example": 3 }, "skipped_documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": [ "string", "null" ] }, "third_party": { "type": [ "string", "null" ] }, "reason": { "type": "string", "example": "Aucun compte d'imputation sur la ligne 2." } } } } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/PeriodLockedOrValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/documents/{importedDocument}": { "get": { "operationId": "companies.documents.show", "tags": [ "Documents" ], "summary": "Document", "description": "With its lines (recorded and actual accounts) and the entry it was booked to.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.documents.show", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "importedDocument", "in": "path", "required": true, "description": "Id of the document.", "schema": { "type": "integer" }, "example": 87 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportedDocument" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/documents/{importedDocument}/lines/{line}": { "patch": { "operationId": "companies.documents.lines.update", "tags": [ "Documents" ], "summary": "Correct the allocation of a line", "description": "Sets the account chosen by the accountant (« actual » layer); `account_id: null` goes back to the recorded account.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.documents.lines.update", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "importedDocument", "in": "path", "required": true, "description": "Id of the document.", "schema": { "type": "integer" }, "example": 87 }, { "name": "line", "in": "path", "required": true, "description": "Id of the line.", "schema": { "type": "integer" }, "example": 3391 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": [ "integer", "null" ], "description": "Postable account." }, "vat_code_id": { "type": [ "integer", "null" ] } } }, "example": { "account_id": 361 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportedDocumentLine" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/documents/{importedDocument}/book": { "post": { "operationId": "companies.documents.book", "tags": [ "Documents" ], "summary": "Book a document", "description": "Posts the entry of the document in the journal resolved by the journal rules.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `period_locked`: the period is locked or the fiscal year is closed; `reason` tells which (`period_locked` or `fiscal_year_closed`)", "x-route-name": "api.v1.companies.documents.book", "x-required-ability": "write", "x-error-codes": [ "period_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "importedDocument", "in": "path", "required": true, "description": "Id of the document.", "schema": { "type": "integer" }, "example": 87 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "201": { "description": "Booked, with `journal_entry`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportedDocument" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/PeriodLockedOrValidationError" } } } }, "/v1/companies/{company}/documents/{importedDocument}/ignore": { "post": { "operationId": "companies.documents.ignore", "tags": [ "Documents" ], "summary": "Ignore or restore a document", "description": "An ignored document is left out of the booking; `restore: true` puts it back to pending. Refused for a booked document.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.documents.ignore", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "importedDocument", "in": "path", "required": true, "description": "Id of the document.", "schema": { "type": "integer" }, "example": 87 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "restore": { "type": "boolean" } } }, "example": { "restore": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportedDocument" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/document-imports": { "get": { "operationId": "companies.document-imports.index", "tags": [ "Document importer" ], "summary": "List the imports", "description": "Polling list of the uploaded files, without `raw_text`.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.document-imports.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "batch_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Comma-separated statuses.", "schema": { "type": "string" }, "example": "ready,needs_review" }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentImport" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "companies.document-imports.store", "tags": [ "Document importer" ], "summary": "Upload files", "description": "Multipart upload of 1 to 20 files, 25 MB each: PDF, images (JPEG, PNG, HEIC, WebP), UBL / CII XML, or a ZIP of those (50 files max, expanded into child imports). Files are stored and queued; call `process` for a synchronous analysis or let the scheduler analyse them within a minute.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 30 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.document-imports.store", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 30, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "files[]": { "type": "array", "items": { "type": "string", "format": "binary" } }, "batch_id": { "type": "string", "format": "uuid", "description": "Reuse a batch to add files to it." } }, "required": [ "files[]" ] } } } }, "responses": { "201": { "description": "Files stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch_id": { "type": "string", "format": "uuid" }, "imports": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentImport" } } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/document-imports/engines": { "get": { "operationId": "companies.document-imports.engines", "tags": [ "Document importer" ], "summary": "Analysis engines", "description": "Engines able to read a document and whether each is configured.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.document-imports.engines", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "engines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "api" }, "configured": { "type": "boolean" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/document-imports/{documentImport}": { "get": { "operationId": "companies.document-imports.show", "tags": [ "Document importer" ], "summary": "Import", "description": "With the extracted data and the text layer.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.document-imports.show", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "documentImport", "in": "path", "required": true, "description": "Id of the import (uploaded file).", "schema": { "type": "integer" }, "example": 311 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentImport" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "companies.document-imports.update", "tags": [ "Document importer" ], "summary": "Correct the extracted data", "description": "Saves corrections without validating. Only for the statuses `ready`, `needs_review` and `duplicate`.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.document-imports.update", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "documentImport", "in": "path", "required": true, "description": "Id of the import (uploaded file).", "schema": { "type": "integer" }, "example": 311 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "extracted": { "$ref": "#/components/schemas/ExtractedDocument" } }, "required": [ "extracted" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentImport" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "operationId": "companies.document-imports.destroy", "tags": [ "Document importer" ], "summary": "Delete an import", "description": "Goes to the recycle bin. A validated import keeps its document.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.document-imports.destroy", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "documentImport", "in": "path", "required": true, "description": "Id of the import (uploaded file).", "schema": { "type": "integer" }, "example": 311 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-Trashed": { "$ref": "#/components/headers/X-Trashed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/companies/{company}/document-imports/{documentImport}/process": { "post": { "operationId": "companies.document-imports.process", "tags": [ "Document importer" ], "summary": "Analyse an import now", "description": "Synchronous analysis (up to two minutes): text layer, extraction, account suggestions, third party matching, duplicate detection. Already analysed: returns the result.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 120 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.document-imports.process", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 120, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "documentImport", "in": "path", "required": true, "description": "Id of the import (uploaded file).", "schema": { "type": "integer" }, "example": 311 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentImport" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/document-imports/{documentImport}/retry": { "post": { "operationId": "companies.document-imports.retry", "tags": [ "Document importer" ], "summary": "Analyse again", "description": "`force` re-analyses a file flagged as the duplicate of another import.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 60 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.document-imports.retry", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 60, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "documentImport", "in": "path", "required": true, "description": "Id of the import (uploaded file).", "schema": { "type": "integer" }, "example": 311 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "force": { "type": "boolean" } } }, "example": { "force": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentImport" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/document-imports/{documentImport}/validate": { "post": { "operationId": "companies.document-imports.validate", "tags": [ "Document importer" ], "summary": "Validate an import", "description": "Creates the document (locked for the shop), books it unless `book: false`, and pushes it to Novadesko when the file is linked (never from the demo). The third party is `third_party_id`, or created from `new_third_party`.\n\nIntegration tokens need the `write` ability.\n\nRate limit: 120 requests per minute (429 beyond, see `Retry-After`).\n\nError codes (`code`):\n- `period_locked`: the period is locked or the fiscal year is closed; `reason` tells which (`period_locked` or `fiscal_year_closed`)", "x-route-name": "api.v1.companies.document-imports.validate", "x-required-ability": "write", "x-rate-limit": { "limit": 120, "window_minutes": 1 }, "x-error-codes": [ "period_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "documentImport", "in": "path", "required": true, "description": "Id of the import (uploaded file).", "schema": { "type": "integer" }, "example": 311 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "extracted": { "$ref": "#/components/schemas/ExtractedDocument" }, "third_party_id": { "type": [ "integer", "null" ] }, "new_third_party": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "supplier", "customer" ] }, "name": { "type": "string" }, "vat_number": { "type": [ "string", "null" ] }, "enterprise_number": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "iban": { "type": [ "string", "null" ] }, "bic": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] } }, "required": [ "name" ] }, "direction": { "type": "string", "enum": [ "purchase", "sale" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": [ "integer", "null" ] }, "vat_code_id": { "type": [ "integer", "null" ] } } } }, "book": { "type": "boolean", "description": "True by default." }, "push_to_novadesko": { "type": [ "boolean", "null" ] }, "force": { "type": "boolean", "description": "Validate despite a duplicate warning." } } }, "example": { "third_party_id": 18, "direction": "purchase", "lines": [ { "account_id": 361, "vat_code_id": 25 } ], "book": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "import": { "$ref": "#/components/schemas/DocumentImport" }, "document": { "$ref": "#/components/schemas/ImportedDocument" }, "entry": { "anyOf": [ { "$ref": "#/components/schemas/JournalEntry" }, { "type": "null" } ] }, "novadesko": { "type": "object", "properties": { "status": { "type": "string", "example": "skipped", "description": "pushed, skipped, failed or not_linked." }, "message": { "type": [ "string", "null" ] } } } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/PeriodLockedOrValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/document-imports/{documentImport}/file": { "get": { "operationId": "document-imports.file", "tags": [ "Document importer" ], "summary": "Signed preview of an uploaded file", "description": "Serves the file inline (or its preview: PDF embedded in a UBL, JPEG converted from HEIC).\n\nAuthorised by the signature of the URL (query parameters `signature` and `expires`), not by a bearer token. The URL is issued by another endpoint and expires.\n\nRate limit: 240 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.document-imports.file", "x-signed-url": true, "x-rate-limit": { "limit": 240, "window_minutes": 1 }, "security": [], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "documentImport", "in": "path", "required": true, "description": "Id of the import (uploaded file).", "schema": { "type": "integer" }, "example": 311 }, { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Expires" }, { "name": "preview", "in": "query", "description": "`0` serves the original file.", "schema": { "type": "string", "enum": [ "0", "1" ] } } ], "responses": { "200": { "description": "The file, inline.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "application/xml": { "schema": { "type": "string" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/bank-transactions": { "get": { "operationId": "companies.bank-transactions.index", "tags": [ "Bank" ], "summary": "List the bank transactions", "description": "Transactions of the CODA statements with the proposed match.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.bank-transactions.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "unmatched", "in": "query", "description": "Pending and without proposal.", "schema": { "type": "boolean" } }, { "name": "journal_id", "in": "query", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "booked", "ignored" ] } }, { "name": "from", "in": "query", "description": "Value date.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "q", "in": "query", "description": "Counterpart, communication or description.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 100, maximum 500).", "schema": { "type": "integer" }, "example": 100 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BankTransaction" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/bank-transactions/match": { "post": { "operationId": "companies.bank-transactions.match", "tags": [ "Bank" ], "summary": "Propose the matches", "description": "Looks for the invoice paid by each pending transaction (structured communication, Novadesko link, amount and third party) and applies the bank rules.\n\nIntegration tokens need the `write` ability.\n\nRate limit: 10 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.bank-transactions.match", "x-required-ability": "write", "x-rate-limit": { "limit": 10, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposals": { "type": "integer", "example": 17 } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/bank-transactions/book-matched": { "post": { "operationId": "companies.bank-transactions.book-matched", "tags": [ "Bank" ], "summary": "Book the matched transactions", "description": "Books every transaction with a high-confidence match (and medium ones with `include_medium`).\n\nIntegration tokens need the `write` ability.\n\nRate limit: 5 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.bank-transactions.book-matched", "x-required-ability": "write", "x-rate-limit": { "limit": 5, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "include_medium": { "type": "boolean" } } }, "example": { "include_medium": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "booked": { "type": "integer", "example": 14 }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "reason": { "type": "string" } } } } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/bank-transactions/{bankTransaction}/book": { "post": { "operationId": "companies.bank-transactions.book", "tags": [ "Bank" ], "summary": "Book a transaction", "description": "Payment of the matched invoice (lettered with it), or allocation to the chosen account (fees, VAT, salaries…).\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `period_locked`: the period is locked or the fiscal year is closed; `reason` tells which (`period_locked` or `fiscal_year_closed`)", "x-route-name": "api.v1.companies.bank-transactions.book", "x-required-ability": "write", "x-error-codes": [ "period_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "bankTransaction", "in": "path", "required": true, "description": "Id of the bank transaction.", "schema": { "type": "integer" }, "example": 951 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": [ "integer", "null" ], "description": "Postable account; absent = payment of the matched invoice." }, "third_party_id": { "type": [ "integer", "null" ] }, "label": { "type": [ "string", "null" ] } } }, "example": { "account_id": 517, "label": "Frais de tenue de compte" } } } }, "responses": { "201": { "description": "Booked, with `journal_entry`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTransaction" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/PeriodLockedOrValidationError" } } } }, "/v1/companies/{company}/bank-transactions/{bankTransaction}/ignore": { "post": { "operationId": "companies.bank-transactions.ignore", "tags": [ "Bank" ], "summary": "Ignore or restore a transaction", "description": "Integration tokens need the `write` ability.", "x-route-name": "api.v1.companies.bank-transactions.ignore", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "bankTransaction", "in": "path", "required": true, "description": "Id of the bank transaction.", "schema": { "type": "integer" }, "example": 951 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "restore": { "type": "boolean" } } }, "example": { "restore": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankTransaction" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/treasury": { "get": { "operationId": "companies.treasury", "tags": [ "Bank" ], "summary": "Treasury", "description": "Accounting balance of each financial journal against the last statement, with the pending transactions.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.treasury", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Treasury" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/bank-rules": { "get": { "operationId": "companies.bank-rules.index", "tags": [ "Bank" ], "summary": "List the bank rules", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.bank-rules.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BankRule" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "companies.bank-rules.store", "tags": [ "Bank" ], "summary": "Create a bank rule", "description": "Allocates the transactions whose field matches the pattern to an account.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.bank-rules.store", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string", "enum": [ "counterpart_name", "counterpart_iban", "communication", "description", "any" ] }, "operator": { "type": "string", "enum": [ "contains", "equals", "starts" ] }, "pattern": { "type": "string" }, "direction": { "type": "string", "enum": [ "in", "out", "any" ] }, "account_id": { "type": "integer", "description": "Postable account." }, "third_party_id": { "type": [ "integer", "null" ] }, "label": { "type": [ "string", "null" ] }, "priority": { "type": "integer", "description": "1 to 999." }, "is_active": { "type": "boolean" } }, "required": [ "name", "field", "pattern", "account_id" ] }, "example": { "name": "Frais bancaires", "field": "description", "operator": "contains", "pattern": "frais de tenue", "direction": "out", "account_id": 517 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankRule" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/bank-rules/{bankRule}": { "patch": { "operationId": "companies.bank-rules.update", "tags": [ "Bank" ], "summary": "Update a bank rule", "description": "Integration tokens need the `write` ability.", "x-route-name": "api.v1.companies.bank-rules.update", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "bankRule", "in": "path", "required": true, "description": "Id of the bank rule.", "schema": { "type": "integer" }, "example": 6 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "field": { "type": "string", "enum": [ "counterpart_name", "counterpart_iban", "communication", "description", "any" ] }, "operator": { "type": "string", "enum": [ "contains", "equals", "starts" ] }, "pattern": { "type": "string" }, "direction": { "type": "string", "enum": [ "in", "out", "any" ] }, "account_id": { "type": "integer", "description": "Postable account." }, "third_party_id": { "type": [ "integer", "null" ] }, "label": { "type": [ "string", "null" ] }, "priority": { "type": "integer", "description": "1 to 999." }, "is_active": { "type": "boolean" } } }, "example": { "is_active": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankRule" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "operationId": "companies.bank-rules.destroy", "tags": [ "Bank" ], "summary": "Delete a bank rule", "description": "Integration tokens need the `write` ability.", "x-route-name": "api.v1.companies.bank-rules.destroy", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "bankRule", "in": "path", "required": true, "description": "Id of the bank rule.", "schema": { "type": "integer" }, "example": 6 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "responses": { "204": { "description": "Done, no body.", "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-Trashed": { "$ref": "#/components/headers/X-Trashed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/companies/{company}/coda-files": { "get": { "operationId": "companies.coda-files.index", "tags": [ "Bank" ], "summary": "List the CODA files", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.coda-files.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "journal_id", "in": "query", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CodaFile" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/coda-files/{codaFile}/download": { "get": { "operationId": "companies.coda-files.download", "tags": [ "Bank" ], "summary": "Download a CODA file", "description": "Original statement file.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.coda-files.download", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "codaFile", "in": "path", "required": true, "description": "Id of the CODA file.", "schema": { "type": "integer" }, "example": 31 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "The CODA file.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" } }, "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/payments/open-items": { "get": { "operationId": "companies.payments.open-items", "tags": [ "Bank" ], "summary": "Supplier items to pay", "description": "Open supplier lines; `payable` is false when the IBAN of the supplier is missing.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.payments.open-items", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "line_id": { "type": "integer" }, "entry_id": { "type": "integer" }, "reference": { "type": "string", "example": "ACH 2026/000412" }, "journal_code": { "type": "string", "example": "ACH" }, "entry_date": { "type": "string", "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "overdue": { "type": "boolean" }, "label": { "type": "string" }, "external_reference": { "type": [ "string", "null" ], "example": "F-2026-0412" }, "structured_communication": { "type": [ "string", "null" ] }, "third_party_id": { "type": "integer" }, "third_party": { "type": "string", "example": "Brasserie Dubuisson SA" }, "iban": { "type": [ "string", "null" ] }, "bic": { "type": [ "string", "null" ] }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "655.82" }, "payable": { "type": "boolean" } } } }, "total": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "655.82" }, "payable_count": { "type": "integer", "example": 1 } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/payments/sepa": { "post": { "operationId": "companies.payments.sepa", "tags": [ "Bank" ], "summary": "Generate a SEPA credit transfer file", "description": "pain.001 XML for the chosen open items, debited from the bank of a financial journal. The file is to be uploaded to the bank: NovaFisko never initiates a payment.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 20 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.payments.sepa", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 20, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "journal_id": { "type": "integer", "description": "Financial journal with an IBAN." }, "line_ids": { "type": "array", "items": { "type": "integer" } }, "execution_date": { "type": "string", "format": "date", "description": "Today or later." } }, "required": [ "journal_id", "line_ids", "execution_date" ] }, "example": { "journal_id": 7, "line_ids": [ 3394, 3410 ], "execution_date": "2026-04-02" } } } }, "responses": { "200": { "description": "SEPA pain.001 file. Headers `X-Sepa-Count` and `X-Sepa-Total` give the number of transfers and their total.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" }, "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/xml": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/vat-codes": { "get": { "operationId": "companies.vat-codes.index", "tags": [ "VAT" ], "summary": "VAT codes", "description": "Codes of the country pack with their rate, nature and declaration grids.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.vat-codes.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "all", "in": "query", "description": "Include the inactive codes.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VatCode" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/vat-codes/{vatCode}": { "patch": { "operationId": "companies.vat-codes.update", "tags": [ "VAT" ], "summary": "Activate or describe a VAT code", "description": "Rates and grids are part of the country pack and cannot be edited.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.vat-codes.update", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "vatCode", "in": "path", "required": true, "description": "Id of the VAT code.", "schema": { "type": "integer" }, "example": 4 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "is_active": { "type": "boolean" }, "description": { "type": [ "string", "null" ] } } }, "example": { "is_active": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatCode" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/vat-declarations": { "get": { "operationId": "companies.vat.index", "tags": [ "VAT" ], "summary": "VAT periods of a year", "description": "Every period of the year with its declaration, or a computed preview when none exists yet.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.vat.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "year", "in": "query", "description": "Current year by default.", "schema": { "type": "integer" }, "example": 2026 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "example": 2026 }, "period_type": { "type": "string", "enum": [ "monthly", "quarterly" ] }, "periods": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "integer", "example": 1 }, "label": { "type": "string", "example": "1T 2026" }, "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" }, "declaration": { "anyOf": [ { "$ref": "#/components/schemas/VatDeclaration" }, { "type": "null" } ] }, "preview": { "anyOf": [ { "$ref": "#/components/schemas/VatComputation" }, { "type": "null" } ] } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "companies.vat.store", "tags": [ "VAT" ], "summary": "Create or refresh a draft declaration", "description": "Computes the grids of the period and stores them as a draft. Calling it again recomputes the draft.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.vat.store", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "example": 2026, "description": "2000 to 2100." }, "period": { "type": "integer", "example": 1, "description": "Month (1-12) or quarter (1-4) according to the VAT regime of the file." } }, "required": [ "year", "period" ] }, "example": { "year": 2026, "period": 1 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatDeclaration" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/vat-declarations/preview": { "get": { "operationId": "companies.vat.preview", "tags": [ "VAT" ], "summary": "Compute a VAT period", "description": "Grids computed from the entries of the period, without saving anything.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.vat.preview", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "year", "in": "query", "required": true, "description": "2000 to 2100.", "schema": { "type": "integer" }, "example": 2026 }, { "name": "period", "in": "query", "required": true, "description": "Month (1-12) or quarter (1-4) according to the VAT regime of the file.", "schema": { "type": "integer" }, "example": 1 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" } } }, { "$ref": "#/components/schemas/VatComputation" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/vat-declarations/intracom-listing": { "get": { "operationId": "companies.vat.intracom-listing", "tags": [ "VAT" ], "summary": "Intra-community listing", "description": "Intra-EU supplies of goods and services per customer for the period. `format=xml` downloads the Intervat file.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.vat.intracom-listing", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "year", "in": "query", "required": true, "description": "2000 to 2100.", "schema": { "type": "integer" }, "example": 2026 }, { "name": "period", "in": "query", "required": true, "description": "Month (1-12) or quarter (1-4) according to the VAT regime of the file.", "schema": { "type": "integer" }, "example": 1 }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "xml" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer" }, "period": { "type": "integer" }, "period_type": { "type": "string" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "clients": { "type": "array", "items": { "type": "object", "properties": { "vat_number": { "type": "string", "example": "NL853746333B01" }, "country": { "type": "string", "example": "NL" }, "name": { "type": "string" }, "code": { "type": "string", "example": "S", "description": "L goods, S services, T triangular." }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } } }, "total": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "total_goods": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "total_services": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/vat-declarations/client-listing/{year}": { "get": { "operationId": "companies.vat.client-listing", "tags": [ "VAT" ], "summary": "Annual customer listing", "description": "Belgian VAT-liable customers of the year with turnover and VAT; `declare` is true above the legal threshold of 250 EUR. `format=xml` downloads the Intervat file.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.vat.client-listing", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "year", "in": "path", "required": true, "description": "Calendar year.", "schema": { "type": "integer" }, "example": 2026 }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "xml" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "example": 2026 }, "clients": { "type": "array", "items": { "type": "object", "properties": { "vat_number": { "type": "string", "example": "BE0403170701" }, "name": { "type": "string", "example": "ACME SA" }, "turnover": { "type": "number", "example": 18250 }, "vat": { "type": "number", "example": 3832.5 }, "declare": { "type": "boolean" } } } }, "total_turnover": { "type": "number" }, "total_vat": { "type": "number" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/vat-declarations/{vatDeclaration}": { "get": { "operationId": "companies.vat.show", "tags": [ "VAT" ], "summary": "VAT declaration", "description": "With its settlement entry once validated.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.vat.show", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "vatDeclaration", "in": "path", "required": true, "description": "Id of the VAT declaration.", "schema": { "type": "integer" }, "example": 14 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatDeclaration" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/vat-declarations/{vatDeclaration}/validate": { "post": { "operationId": "companies.vat.validate", "tags": [ "VAT" ], "summary": "Validate a declaration", "description": "Freezes the grids and posts the VAT settlement entry (accounts of `settings.auto_entries.vat`). Emits the webhook `vat.declaration_validated`.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `period_locked`: the period is locked or the fiscal year is closed; `reason` tells which (`period_locked` or `fiscal_year_closed`)", "x-route-name": "api.v1.companies.vat.validate", "x-required-ability": "write", "x-error-codes": [ "period_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "vatDeclaration", "in": "path", "required": true, "description": "Id of the VAT declaration.", "schema": { "type": "integer" }, "example": 14 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatDeclaration" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/PeriodLockedOrValidationError" } } } }, "/v1/companies/{company}/vat-declarations/{vatDeclaration}/submit": { "post": { "operationId": "companies.vat.submit", "tags": [ "VAT" ], "summary": "Mark a declaration as submitted", "description": "Records the Intervat reference. NovaFisko does not file the declaration itself: download the XML and upload it on Intervat.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.vat.submit", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "vatDeclaration", "in": "path", "required": true, "description": "Id of the VAT declaration.", "schema": { "type": "integer" }, "example": 14 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": [ "string", "null" ], "description": "Intervat receipt reference." } } }, "example": { "reference": "INTERVAT-2026-04-0098123" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VatDeclaration" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/vat-declarations/{vatDeclaration}/xml": { "get": { "operationId": "companies.vat.xml", "tags": [ "VAT" ], "summary": "Intervat XML of a declaration", "description": "File ready to upload on Intervat (VATConsignment).\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.vat.xml", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "vatDeclaration", "in": "path", "required": true, "description": "Id of the VAT declaration.", "schema": { "type": "integer" }, "example": 14 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Intervat XML file.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" } }, "content": { "application/xml": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/fixed-assets": { "get": { "operationId": "companies.fixed-assets.index", "tags": [ "Fixed assets" ], "summary": "Fixed asset register", "description": "With the depreciation plan of each asset.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.fixed-assets.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FixedAsset" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "companies.fixed-assets.store", "tags": [ "Fixed assets" ], "summary": "Create a fixed asset", "description": "Builds the depreciation plan (linear or declining, pro rata temporis) and resolves the asset, depreciation and expense accounts.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.fixed-assets.store", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "category": { "type": "string", "enum": [ "it_equipment", "vehicle", "furniture", "machinery", "building", "software", "other" ] }, "asset_group": { "type": [ "string", "null" ] }, "investment_deduction_pct": { "type": [ "number", "null" ], "description": "0 to 100." }, "investment_deduction_spread": { "type": "boolean" }, "asset_account_id": { "type": [ "integer", "null" ], "description": "Class 2 account; resolved from the category when absent." }, "acquisition_date": { "type": "string", "format": "date" }, "acquisition_cost": { "type": "string", "description": "Decimal, excl. VAT." }, "residual_value": { "type": [ "string", "null" ], "description": "Decimal." }, "useful_life_years": { "type": "integer", "description": "1 to 50." }, "method": { "type": "string", "enum": [ "linear", "declining" ] }, "prorata_temporis": { "type": "boolean", "description": "True by default." }, "start_date": { "type": [ "string", "null" ], "format": "date", "description": "Start of the depreciation; the acquisition date by default." }, "notes": { "type": [ "string", "null" ] } }, "required": [ "name", "category", "acquisition_date", "acquisition_cost", "useful_life_years" ] }, "example": { "name": "Four mixte Rational", "category": "machinery", "acquisition_date": "2026-02-01", "acquisition_cost": "12400.00", "useful_life_years": 5 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAsset" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/fixed-assets/groups/{fiscalYear}": { "get": { "operationId": "companies.fixed-assets.groups", "tags": [ "Fixed assets" ], "summary": "Depreciation table per group", "description": "Acquisition cost, accumulated depreciation, depreciation of the year and net book value per group, for a fiscal year.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.fixed-assets.groups", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "fiscal_year": { "type": "string", "example": "2026" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "example": "machinery" }, "count": { "type": "integer", "example": 1 }, "acquisition_cost": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "12400.00" }, "accumulated": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "2269.37" }, "net_book_value": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "10130.63" }, "year_depreciation": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "2269.37" }, "investment_deduction": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "assets": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } }, "totals": { "type": "object", "properties": { "acquisition_cost": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "accumulated": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "net_book_value": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "year_depreciation": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "investment_deduction": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/fixed-assets/{fixedAsset}": { "get": { "operationId": "companies.fixed-assets.show", "tags": [ "Fixed assets" ], "summary": "Fixed asset", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.fixed-assets.show", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fixedAsset", "in": "path", "required": true, "description": "Id of the fixed asset.", "schema": { "type": "integer" }, "example": 9 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAsset" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "companies.fixed-assets.update", "tags": [ "Fixed assets" ], "summary": "Update a fixed asset", "description": "The plan is rebuilt for the years not booked yet.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.fixed-assets.update", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fixedAsset", "in": "path", "required": true, "description": "Id of the fixed asset.", "schema": { "type": "integer" }, "example": 9 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string", "enum": [ "it_equipment", "vehicle", "furniture", "machinery", "building", "software", "other" ] }, "asset_group": { "type": [ "string", "null" ] }, "investment_deduction_pct": { "type": [ "number", "null" ] }, "investment_deduction_spread": { "type": "boolean" }, "asset_account_id": { "type": [ "integer", "null" ] }, "residual_value": { "type": "string" }, "useful_life_years": { "type": "integer" }, "method": { "type": "string", "enum": [ "linear", "declining" ] }, "prorata_temporis": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "fully_depreciated", "disposed" ] }, "notes": { "type": [ "string", "null" ] } } }, "example": { "useful_life_years": 7 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAsset" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/fixed-assets/book-period/{fiscalYear}": { "post": { "operationId": "companies.fixed-assets.book-period", "tags": [ "Fixed assets" ], "summary": "Book the depreciation of a period", "description": "One miscellaneous entry for every asset, for a month of the fiscal year. 200 with `entry: null` when there is nothing to book.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.fixed-assets.book-period", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "period_number": { "type": "integer", "description": "1 to 12." } }, "required": [ "period_number" ] }, "example": { "period_number": 3 } } } }, "responses": { "200": { "description": "Nothing to book", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "anyOf": [ { "$ref": "#/components/schemas/JournalEntry" }, { "type": "null" } ] }, "period": { "type": "string", "example": "Mars 2026" } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "201": { "description": "Depreciation booked", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "$ref": "#/components/schemas/JournalEntry" }, "period": { "type": "string", "example": "Mars 2026" } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/fixed-assets/{fixedAsset}/book/{fiscalYear}": { "post": { "operationId": "companies.fixed-assets.book", "tags": [ "Fixed assets" ], "summary": "Book the yearly depreciation of an asset", "description": "Miscellaneous entry 6302 / 2x09 for the fiscal year.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `period_locked`: the period is locked or the fiscal year is closed; `reason` tells which (`period_locked` or `fiscal_year_closed`)", "x-route-name": "api.v1.companies.fixed-assets.book", "x-required-ability": "write", "x-error-codes": [ "period_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fixedAsset", "in": "path", "required": true, "description": "Id of the fixed asset.", "schema": { "type": "integer" }, "example": 9 }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixedAsset" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/PeriodLockedOrValidationError" } } } }, "/v1/companies/{company}/fixed-assets/{fixedAsset}/dispose": { "post": { "operationId": "companies.fixed-assets.dispose", "tags": [ "Fixed assets" ], "summary": "Dispose of an asset", "description": "Sale (price above 0) or scrapping (price 0): posts the disposal entry with the gain or loss.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.fixed-assets.dispose", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fixedAsset", "in": "path", "required": true, "description": "Id of the fixed asset.", "schema": { "type": "integer" }, "example": 9 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "sale_price": { "type": [ "string", "null" ], "description": "Decimal, excl. VAT." }, "label": { "type": [ "string", "null" ] } }, "required": [ "date" ] }, "example": { "date": "2026-09-30", "sale_price": "4500.00" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset": { "$ref": "#/components/schemas/FixedAsset" }, "entry": { "$ref": "#/components/schemas/JournalEntry" } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/journals/{journal}/entries": { "get": { "operationId": "companies.reports.journal", "tags": [ "Reports" ], "summary": "Entries of a journal", "description": "Full entries of the journal over a date range, in number order (journal book).\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.reports.journal", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "journal", "in": "path", "required": true, "description": "Id of the journal.", "schema": { "type": "integer" }, "example": 3 }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntry" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/fiscal-years/{fiscalYear}/trial-balance": { "get": { "operationId": "companies.reports.trial-balance", "tags": [ "Reports" ], "summary": "Trial balance", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.reports.trial-balance", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "include_empty", "in": "query", "description": "Include the accounts without movement.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "fiscal_year": { "type": "string", "example": "2026" }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "integer", "example": 223 }, "number": { "type": "string", "example": "400000" }, "label": { "type": "string", "example": "Clients" }, "type": { "type": "string", "example": "asset" }, "debit": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1210.00" }, "credit": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "debit_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1210.00" }, "credit_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1210.00" } } } }, "totals": { "type": "object", "properties": { "debit": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1512.50" }, "credit": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1512.50" }, "is_balanced": { "type": "boolean" }, "result": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "750.00", "description": "Result of the period." } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/fiscal-years/{fiscalYear}/balance-by-period": { "get": { "operationId": "companies.reports.balance-by-period", "tags": [ "Reports" ], "summary": "Balance by period", "description": "One column per period of the fiscal year.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.reports.balance-by-period", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "fiscal_year": { "type": "string", "example": "2026" }, "periods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "integer" }, "label": { "type": "string", "example": "Janvier 2026" }, "is_locked": { "type": "boolean" } } } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "integer", "example": 223 }, "number": { "type": "string", "example": "400000" }, "label": { "type": "string", "example": "Clients" }, "type": { "type": "string", "example": "asset" }, "periods": { "type": "array", "items": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } }, "total": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/fiscal-years/{fiscalYear}/financial-statements": { "get": { "operationId": "companies.reports.financial-statements", "tags": [ "Reports" ], "summary": "Balance sheet and income statement", "description": "Belgian legal scheme (BNB / NBB headings), in real time.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.reports.financial-statements", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "name": "to", "in": "query", "description": "Situation at this date.", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "fiscal_year": { "type": "string", "example": "2026" }, "to": { "type": "string", "format": "date" }, "scheme": { "type": "string", "example": "BE" }, "balance_sheet": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "20/28" }, "label": { "type": "string", "example": "ACTIFS IMMOBILISÉS" }, "side": { "type": "string", "enum": [ "asset", "liability" ] }, "group": { "type": "boolean" }, "amount": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$" } } } }, "totals": { "type": "object", "properties": { "assets": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1262.50" }, "liabilities": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1262.50" }, "is_balanced": { "type": "boolean" } } }, "income_statement": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "70" }, "label": { "type": "string", "example": "Chiffre d'affaires" }, "side": { "type": "string", "enum": [ "income", "expense" ] }, "detail": { "type": "boolean" }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1000.00" } } } }, "result": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "750.00" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/fiscal-years/{fiscalYear}/general-ledger/{account}": { "get": { "operationId": "companies.reports.general-ledger", "tags": [ "Reports" ], "summary": "General ledger of an account", "description": "Movements of one account with the running balance.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.reports.general-ledger", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "name": "account", "in": "path", "required": true, "description": "Id of the account (not its number).", "schema": { "type": "integer" }, "example": 223 }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "integer", "example": 223 }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "opening_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "movements": { "type": "array", "items": { "type": "object", "properties": { "line_id": { "type": "integer" }, "entry_id": { "type": "integer" }, "entry_date": { "type": "string", "format": "date" }, "journal": { "type": "string", "example": "VEN" }, "document": { "type": "string", "example": "2026/000412" }, "label": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "third_party": { "type": [ "string", "null" ] }, "debit": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "credit": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "reconciliation_code": { "type": [ "string", "null" ] } } } }, "totals": { "type": "object", "properties": { "debit": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "credit": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/fiscal-years/{fiscalYear}/consistency": { "get": { "operationId": "companies.reports.consistency", "tags": [ "Reports" ], "summary": "Consistency of the fiscal year", "description": "Gaps in the numbering, entries whose period does not match their date, entries outside the fiscal year.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.reports.consistency", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "fiscal_year": { "type": "string", "example": "2026" }, "missing_numbers": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "period_mismatches": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "entries_outside_fiscal_year": { "type": "integer", "example": 0 }, "is_consistent": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/third-party-balance/{type}": { "get": { "operationId": "companies.reports.third-party-balance", "tags": [ "Reports" ], "summary": "Customer or supplier balance", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.reports.third-party-balance", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "type", "in": "path", "required": true, "description": "Side of the balance.", "schema": { "type": "string", "enum": [ "customer", "supplier" ] }, "example": "customer" }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "third_party_id": { "type": "integer" }, "code": { "type": "string", "example": "ACME" }, "name": { "type": "string", "example": "ACME SA" }, "debit": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "credit": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "outstanding": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1210.00" }, "open_items": { "type": "integer", "example": 1 } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/aged-balance/{type}": { "get": { "operationId": "companies.reports.aged-balance", "tags": [ "Reports" ], "summary": "Aged balance", "description": "Open amounts per third party, split by age: not due, 1-30, 31-60, 61-90 and more than 90 days.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.reports.aged-balance", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "type", "in": "path", "required": true, "description": "Side of the balance.", "schema": { "type": "string", "enum": [ "customer", "supplier" ] }, "example": "customer" }, { "name": "to", "in": "query", "description": "Today by default.", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "example": "customer" }, "to": { "type": "string", "format": "date" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "third_party_id": { "type": "integer" }, "code": { "type": "string" }, "name": { "type": "string" }, "total": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "current": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "d30": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "d60": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "d90": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "d90plus": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } } }, "totals": { "type": "object", "properties": { "current": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "d30": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "d60": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "d90": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "d90plus": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "total": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/analytic-codes": { "get": { "operationId": "companies.analytic-codes.index", "tags": [ "Analytics & budgets" ], "summary": "Analytic codes", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.analytic-codes.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "axis", "in": "query", "schema": { "type": "string", "enum": [ "cost_center", "project" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticCode" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "companies.analytic-codes.store", "tags": [ "Analytics & budgets" ], "summary": "Create an analytic code", "description": "Integration tokens need the `write` ability.", "x-route-name": "api.v1.companies.analytic-codes.store", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "axis": { "type": "string", "enum": [ "cost_center", "project" ] }, "code": { "type": "string", "description": "Unique per axis, 20 max." }, "label": { "type": "string" }, "is_active": { "type": "boolean" } }, "required": [ "axis", "code", "label" ] }, "example": { "axis": "cost_center", "code": "SALLE", "label": "Salle" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticCode" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/analytic-codes/{analyticCode}": { "patch": { "operationId": "companies.analytic-codes.update", "tags": [ "Analytics & budgets" ], "summary": "Update an analytic code", "description": "Integration tokens need the `write` ability.", "x-route-name": "api.v1.companies.analytic-codes.update", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "analyticCode", "in": "path", "required": true, "description": "Id of the analytic code.", "schema": { "type": "integer" }, "example": 2 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" }, "is_active": { "type": "boolean" } } }, "example": { "is_active": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticCode" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/fiscal-years/{fiscalYear}/analytic-report": { "get": { "operationId": "companies.reports.analytic", "tags": [ "Analytics & budgets" ], "summary": "Analytic report", "description": "Expenses, income and result per analytic code.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.reports.analytic", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "name": "axis", "in": "query", "schema": { "type": "string", "enum": [ "cost_center", "project" ] } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "axis": { "type": "string" }, "fiscal_year": { "type": "string" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "example": "SALLE" }, "label": { "type": [ "string", "null" ] }, "expenses": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "income": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "result": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "integer", "example": 223 }, "number": { "type": "string", "example": "400000" }, "label": { "type": "string", "example": "Clients" }, "type": { "type": "string", "example": "asset" }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/fiscal-years/{fiscalYear}/budgets": { "get": { "operationId": "companies.budgets.index", "tags": [ "Analytics & budgets" ], "summary": "Budget cells", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.budgets.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "name": "scenario", "in": "query", "description": "`default` when absent.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Budget" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "operationId": "companies.budgets.save", "tags": [ "Analytics & budgets" ], "summary": "Save budget cells", "description": "Batch of cells (account × period, optionally × cost centre). An amount of 0 deletes the cell; `spread_yearly` spreads a yearly amount over twelve months.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.budgets.save", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scenario": { "type": "string" }, "cells": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "integer" }, "cost_center_id": { "type": [ "integer", "null" ] }, "period_number": { "type": "integer", "description": "1 to 12." }, "amount": { "type": "string", "description": "Decimal." } }, "required": [ "account_id", "period_number", "amount" ] } }, "spread_yearly": { "type": "boolean" } }, "required": [ "cells" ] }, "example": { "cells": [ { "account_id": 378, "period_number": 1, "amount": "18000.00" } ], "spread_yearly": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "saved": { "type": "integer", "example": 1 } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/fiscal-years/{fiscalYear}/budget-report": { "get": { "operationId": "companies.reports.budget", "tags": [ "Analytics & budgets" ], "summary": "Budget against actuals", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.reports.budget", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "name": "scenario", "in": "query", "schema": { "type": "string" } }, { "name": "cost_center_id", "in": "query", "schema": { "type": "integer" } }, { "name": "upto_period", "in": "query", "description": "1 to 12.", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "scenario": { "type": "string" }, "fiscal_year": { "type": "string" }, "upto_period": { "type": "integer" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "integer", "example": 223 }, "number": { "type": "string", "example": "400000" }, "label": { "type": "string", "example": "Clients" }, "type": { "type": "string", "example": "asset" }, "budget": { "type": "object", "additionalProperties": true, "description": "Period number => amount." }, "actual": { "type": "object", "additionalProperties": true, "description": "Period number => amount." }, "budget_ytd": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "actual_ytd": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "variance": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "variance_pct": { "type": [ "number", "null" ] }, "budget_year": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } } }, "totals": { "type": "object", "properties": { "expenses_minus_income_budget": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" }, "expenses_minus_income_actual": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/exports": { "get": { "operationId": "companies.exports.index", "tags": [ "Exports" ], "summary": "Catalogue of exports", "description": "Every export with its group, formats and parameters. `types` keeps the historical list of CSV codes.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.exports.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "types": { "type": "array", "items": { "type": "string" } }, "formats": { "type": "array", "items": { "type": "string", "enum": [ "pdf", "xlsx", "csv" ] } }, "default_format": { "type": "string", "example": "csv" }, "full_dossier": { "type": "string", "example": "zip" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "books", "statements", "vat", "third_parties", "assets", "data" ] }, "label": { "type": "string", "example": "Livres comptables" } } } }, "common_params": { "type": "array", "items": { "type": "string" } }, "catalog": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "general-ledger" }, "label": { "type": "string", "example": "Grand livre" }, "description": { "type": "string" }, "group": { "type": "string", "example": "books" }, "group_label": { "type": "string" }, "formats": { "type": "array", "items": { "type": "string" } }, "dated": { "type": "boolean" }, "requires_fiscal_year": { "type": "boolean" }, "params": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/exports/full-dossier/{fiscalYear}": { "get": { "operationId": "companies.exports.full-dossier", "tags": [ "Exports" ], "summary": "Full dossier (ZIP)", "description": "Every book, statement, VAT document, third party listing, fixed asset table and the source documents of the fiscal year, in numbered folders with a manifest of SHA-256 fingerprints.\n\nIntegration tokens need the `read` ability.\n\nRate limit: 10 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.exports.full-dossier", "x-required-ability": "read", "x-rate-limit": { "limit": 10, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "fiscalYear", "in": "path", "required": true, "description": "Id of the fiscal year.", "schema": { "type": "integer" }, "example": 2 }, { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "ZIP archive.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/exports/{type}/preview-url": { "get": { "operationId": "companies.exports.preview-url", "tags": [ "Exports" ], "summary": "Signed preview URL of an export", "description": "URL valid 15 minutes that serves the PDF inline (preview pane).\n\nIntegration tokens need the `read` ability.\n\nRate limit: 60 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.exports.preview-url", "x-required-ability": "read", "x-rate-limit": { "limit": 60, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "type", "in": "path", "required": true, "description": "Export code from the catalogue of `GET exports` (`journals`, `general-ledger`, `trial-balance`, `vat-declaration`, …).", "schema": { "type": "string" }, "example": "trial-balance" }, { "name": "fiscal_year_id", "in": "query", "description": "The current fiscal year when absent.", "schema": { "type": "integer" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } }, { "name": "account_from", "in": "query", "description": "general-ledger.", "schema": { "type": "string" } }, { "name": "account_to", "in": "query", "description": "general-ledger.", "schema": { "type": "string" } }, { "name": "scheme", "in": "query", "description": "annual-accounts.", "schema": { "type": "string", "enum": [ "abbreviated", "micro" ] } }, { "name": "general_meeting_date", "in": "query", "description": "annual-accounts.", "schema": { "type": "string", "format": "date" } }, { "name": "declaration_id", "in": "query", "description": "vat-declaration.", "schema": { "type": "integer" } }, { "name": "year", "in": "query", "description": "intracom-listing.", "schema": { "type": "integer" } }, { "name": "period", "in": "query", "description": "intracom-listing.", "schema": { "type": "integer" } }, { "name": "third_party_id", "in": "query", "description": "third-party-ledger.", "schema": { "type": "integer" } }, { "name": "party_type", "in": "query", "description": "third-party-ledger.", "schema": { "type": "string", "enum": [ "customer", "supplier" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expires_in": { "type": "integer", "example": 900, "description": "Seconds." }, "format": { "type": "string", "example": "pdf" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/exports/{type}": { "get": { "operationId": "companies.exports.download", "tags": [ "Exports" ], "summary": "Download an export", "description": "Codes: journals, purchases, sales, financial, miscellaneous, general-ledger, trial-balance, balance-by-period, financial-statements, annual-accounts, vat-summary, vat-declaration, customer-listing, intracom-listing, third-parties, customer-balance, supplier-balance, aged-customers, aged-suppliers, third-party-ledger, fixed-assets, accounts, documents, audit-trail. Generation is synchronous. PDFs of a period that is not locked carry a « provisional » mention.\n\nIntegration tokens need the `read` ability.\n\nRate limit: 30 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.exports.download", "x-required-ability": "read", "x-rate-limit": { "limit": 30, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "type", "in": "path", "required": true, "description": "Export code from the catalogue of `GET exports` (`journals`, `general-ledger`, `trial-balance`, `vat-declaration`, …).", "schema": { "type": "string" }, "example": "trial-balance" }, { "name": "format", "in": "query", "description": "CSV by default.", "schema": { "type": "string", "enum": [ "pdf", "xlsx", "csv" ] } }, { "name": "fiscal_year_id", "in": "query", "description": "The current fiscal year when absent.", "schema": { "type": "integer" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } }, { "name": "account_from", "in": "query", "description": "general-ledger.", "schema": { "type": "string" } }, { "name": "account_to", "in": "query", "description": "general-ledger.", "schema": { "type": "string" } }, { "name": "scheme", "in": "query", "description": "annual-accounts.", "schema": { "type": "string", "enum": [ "abbreviated", "micro" ] } }, { "name": "general_meeting_date", "in": "query", "description": "annual-accounts.", "schema": { "type": "string", "format": "date" } }, { "name": "declaration_id", "in": "query", "description": "vat-declaration.", "schema": { "type": "integer" } }, { "name": "year", "in": "query", "description": "intracom-listing.", "schema": { "type": "integer" } }, { "name": "period", "in": "query", "description": "intracom-listing.", "schema": { "type": "integer" } }, { "name": "third_party_id", "in": "query", "description": "third-party-ledger.", "schema": { "type": "integer" } }, { "name": "party_type", "in": "query", "description": "third-party-ledger.", "schema": { "type": "string", "enum": [ "customer", "supplier" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "The file.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" }, "X-Export-Fingerprint": { "$ref": "#/components/headers/X-Export-Fingerprint" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string" } }, "text/csv": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/exports/{type}/view": { "get": { "operationId": "exports.view", "tags": [ "Exports" ], "summary": "Inline PDF of an export (signed)", "description": "Target of the URL returned by `preview-url`.\n\nAuthorised by the signature of the URL (query parameters `signature` and `expires`), not by a bearer token. The URL is issued by another endpoint and expires.\n\nRate limit: 30 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.exports.view", "x-signed-url": true, "x-rate-limit": { "limit": 30, "window_minutes": 1 }, "security": [], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "type", "in": "path", "required": true, "description": "Export code from the catalogue of `GET exports` (`journals`, `general-ledger`, `trial-balance`, `vat-declaration`, …).", "schema": { "type": "string" }, "example": "trial-balance" }, { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Expires" } ], "responses": { "200": { "description": "The PDF, inline.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/peppol": { "get": { "operationId": "companies.peppol.show", "tags": [ "Peppol" ], "summary": "Peppol state of the file", "description": "Registration, transport options, SMP publication, supported documents and what blocks a registration.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.peppol.show", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolState" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "companies.peppol.destroy", "tags": [ "Peppol" ], "summary": "Unregister the file from Peppol", "description": "Archives the account at the access point and records the reason.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.", "x-route-name": "api.v1.companies.peppol.destroy", "x-required-ability": "write", "x-demo-blocked": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason_type": { "type": "string", "enum": [ "expensive", "accountant", "other" ] }, "custom_reason": { "type": [ "string", "null" ], "description": "Required when the reason is `other`." } }, "required": [ "reason_type" ] }, "example": { "reason_type": "accountant" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolState" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-Trashed": { "$ref": "#/components/headers/X-Trashed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Refused: missing data on the file, provider error or not registered. `blocker_codes` lists the machine reasons and `state` carries the current Peppol state.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "blockers": { "type": "array", "items": { "type": "string" } }, "blocker_codes": { "type": "array", "items": { "type": "string" } }, "state": { "$ref": "#/components/schemas/PeppolState" } } } ] }, "example": { "message": "Le numéro de TVA du dossier est requis pour l'inscription Peppol.", "errors": { "peppol": [ "Le numéro de TVA du dossier est requis pour l'inscription Peppol." ] }, "blockers": [ "Numéro de TVA manquant" ], "blocker_codes": [ "missing_vat_number" ] } } } } } } }, "/v1/companies/{company}/peppol/register": { "post": { "operationId": "companies.peppol.register", "tags": [ "Peppol" ], "summary": "Register the file on Peppol", "description": "Creates the account at the access point (B2Brouter) and publishes the participant `0208:`. 201 for a new registration, 200 when it was already active. Emits the webhook `peppol.status_changed`.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 6 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.peppol.register", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 6, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": [ "string", "null" ], "format": "email", "description": "Contact of the registration." }, "phone": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "province": { "type": [ "string", "null" ] }, "options": { "type": "object", "properties": { "round_before_sum": { "type": [ "boolean", "null" ] }, "apply_taxes_per_line": { "type": [ "boolean", "null" ] }, "registered_for_empl_tax": { "type": [ "boolean", "null" ] } } } } }, "example": { "email": "gerant@comptoir-montois.example", "address": "Grand-Place 14", "postal_code": "7000", "city": "Mons" } } } }, "responses": { "200": { "description": "Already registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolState" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "201": { "description": "Registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolState" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Refused: missing data on the file, provider error or not registered. `blocker_codes` lists the machine reasons and `state` carries the current Peppol state.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "blockers": { "type": "array", "items": { "type": "string" } }, "blocker_codes": { "type": "array", "items": { "type": "string" } }, "state": { "$ref": "#/components/schemas/PeppolState" } } } ] }, "example": { "message": "Le numéro de TVA du dossier est requis pour l'inscription Peppol.", "errors": { "peppol": [ "Le numéro de TVA du dossier est requis pour l'inscription Peppol." ] }, "blockers": [ "Numéro de TVA manquant" ], "blocker_codes": [ "missing_vat_number" ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/peppol/refresh": { "post": { "operationId": "companies.peppol.refresh", "tags": [ "Peppol" ], "summary": "Refresh the Peppol state", "description": "Reads the account at the access point and the network (SML / SMP) again.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 12 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.peppol.refresh", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 12, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolState" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Refused: missing data on the file, provider error or not registered. `blocker_codes` lists the machine reasons and `state` carries the current Peppol state.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "blockers": { "type": "array", "items": { "type": "string" } }, "blocker_codes": { "type": "array", "items": { "type": "string" } }, "state": { "$ref": "#/components/schemas/PeppolState" } } } ] }, "example": { "message": "Le numéro de TVA du dossier est requis pour l'inscription Peppol.", "errors": { "peppol": [ "Le numéro de TVA du dossier est requis pour l'inscription Peppol." ] }, "blockers": [ "Numéro de TVA manquant" ], "blocker_codes": [ "missing_vat_number" ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/peppol/transport": { "patch": { "operationId": "companies.peppol.transport", "tags": [ "Peppol" ], "summary": "Update the transport options", "description": "Reception and the document families received through Peppol.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.", "x-route-name": "api.v1.companies.peppol.transport", "x-required-ability": "write", "x-demo-blocked": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": [ "boolean", "null" ] }, "reception": { "type": [ "boolean", "null" ] }, "standard_documents": { "type": [ "boolean", "null" ] }, "invoice": { "type": [ "boolean", "null" ] }, "credit_note": { "type": [ "boolean", "null" ] }, "self_billing": { "type": [ "boolean", "null" ] }, "order": { "type": [ "boolean", "null" ] }, "application_response": { "type": [ "boolean", "null" ] } } }, "example": { "reception": true, "credit_note": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolState" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "description": "Refused: missing data on the file, provider error or not registered. `blocker_codes` lists the machine reasons and `state` carries the current Peppol state.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "blockers": { "type": "array", "items": { "type": "string" } }, "blocker_codes": { "type": "array", "items": { "type": "string" } }, "state": { "$ref": "#/components/schemas/PeppolState" } } } ] }, "example": { "message": "Le numéro de TVA du dossier est requis pour l'inscription Peppol.", "errors": { "peppol": [ "Le numéro de TVA du dossier est requis pour l'inscription Peppol." ] }, "blockers": [ "Numéro de TVA manquant" ], "blocker_codes": [ "missing_vat_number" ] } } } } } } }, "/v1/companies/{company}/peppol/lookup": { "get": { "operationId": "companies.peppol.lookup", "tags": [ "Peppol" ], "summary": "Look a participant up on the Peppol network", "description": "By identifier (`0208:0402531376`) or by VAT / enterprise number and country. Reads the SML and the SMP of the participant.\n\nIntegration tokens need the `read` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 30 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.peppol.lookup", "x-required-ability": "read", "x-demo-blocked": true, "x-rate-limit": { "limit": 30, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "identifier", "in": "query", "schema": { "type": "string" }, "example": "0208:0402531376" }, { "name": "vat", "in": "query", "schema": { "type": "string" }, "example": "BE0402531376" }, { "name": "country", "in": "query", "schema": { "type": "string" }, "example": "BE" }, { "name": "enterprise_number", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolThirdPartyStatus" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/peppol/document-types": { "get": { "operationId": "companies.peppol.document-types", "tags": [ "Peppol" ], "summary": "Supported Peppol document types", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.peppol.document-types", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "document_types": { "type": "array", "items": { "$ref": "#/components/schemas/PeppolDocumentType" } }, "families": { "type": "array", "items": { "type": "string", "description": "billing, belgium, ordering…" } }, "identifier_schemes": { "type": "object", "additionalProperties": true, "description": "Country => ISO 6523 scheme (BE: 0208)." } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/peppol/logs": { "get": { "operationId": "companies.peppol.logs", "tags": [ "Peppol" ], "summary": "Calls to the access point", "description": "Last calls made for the file, for support.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.peppol.logs", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "limit", "in": "query", "description": "1 to 200, 50 by default.", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/third-parties/peppol/check-all": { "post": { "operationId": "companies.third-parties.peppol.check-all", "tags": [ "Peppol" ], "summary": "Check the Peppol status of every third party", "description": "Up to 100 third parties per call.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 6 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.third-parties.peppol.check-all", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 6, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "only_stale": { "type": [ "boolean", "null" ], "description": "Only the statuses older than 7 days." } } }, "example": { "only_stale": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checked": { "type": "integer", "example": 42 }, "registered": { "type": "integer", "example": 17 }, "errors": { "type": "integer", "example": 0 }, "skipped": { "type": "integer", "example": 1, "description": "Third parties without a usable identifier." } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/third-parties/{thirdParty}/peppol": { "get": { "operationId": "companies.third-parties.peppol", "tags": [ "Peppol" ], "summary": "Peppol status of a third party", "description": "Cached 7 days; `refresh=1` asks the network again.\n\nIntegration tokens need the `read` ability.\n\nRate limit: 60 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.third-parties.peppol", "x-required-ability": "read", "x-rate-limit": { "limit": 60, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "thirdParty", "in": "path", "required": true, "description": "Id of the third party.", "schema": { "type": "integer" }, "example": 18 }, { "name": "refresh", "in": "query", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolThirdPartyStatus" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/integrations": { "get": { "operationId": "companies.integrations.index", "tags": [ "Integrations" ], "summary": "Catalogue of integrations", "description": "Every integration with its status, its configuration schema and the connection of the file.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.integrations.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "lang", "in": "query", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "integrations": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/integrations/{integration}/activate": { "post": { "operationId": "companies.integrations.activate", "tags": [ "Integrations" ], "summary": "Activate an integration", "description": "Integration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nError codes (`code`):\n- `integration_error`: generic driver error\n- `not_available`: integration not available yet\n- `not_connected`: the integration is not active on the file\n- `integration_inactive`: the integration is switched off\n- `no_driver`: nothing to run for this integration\n- `not_linked`: the file is not linked to the external system\n- `use_open_tab`: managed from its own tab (Peppol)\n- `file_required`: a file is expected\n- `file_too_large`: file above the size limit\n- `sync_failed`: the run failed\n- `novadesko_locked`: locked on the Novadesko side", "x-route-name": "api.v1.companies.integrations.activate", "x-required-ability": "write", "x-demo-blocked": true, "x-error-codes": [ "integration_error", "not_available", "not_connected", "integration_inactive", "no_driver", "not_linked", "use_open_tab", "file_required", "file_too_large", "sync_failed", "novadesko_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "integration", "in": "path", "required": true, "description": "Slug of the integration (`novadesko`, `peppol`, `file_import`, …).", "schema": { "type": "string" }, "example": "novadesko" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Values of the configuration schema." } } }, "example": { "config": {} } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Integration" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/integrations/{integration}/deactivate": { "post": { "operationId": "companies.integrations.deactivate", "tags": [ "Integrations" ], "summary": "Deactivate an integration", "description": "Integration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nError codes (`code`):\n- `integration_error`: generic driver error\n- `not_available`: integration not available yet\n- `not_connected`: the integration is not active on the file\n- `integration_inactive`: the integration is switched off\n- `no_driver`: nothing to run for this integration\n- `not_linked`: the file is not linked to the external system\n- `use_open_tab`: managed from its own tab (Peppol)\n- `file_required`: a file is expected\n- `file_too_large`: file above the size limit\n- `sync_failed`: the run failed\n- `novadesko_locked`: locked on the Novadesko side", "x-route-name": "api.v1.companies.integrations.deactivate", "x-required-ability": "write", "x-demo-blocked": true, "x-error-codes": [ "integration_error", "not_available", "not_connected", "integration_inactive", "no_driver", "not_linked", "use_open_tab", "file_required", "file_too_large", "sync_failed", "novadesko_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "integration", "in": "path", "required": true, "description": "Slug of the integration (`novadesko`, `peppol`, `file_import`, …).", "schema": { "type": "string" }, "example": "novadesko" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Integration" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/integrations/{integration}/config": { "patch": { "operationId": "companies.integrations.config", "tags": [ "Integrations" ], "summary": "Update the configuration", "description": "Secrets are stored encrypted and returned masked.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nError codes (`code`):\n- `integration_error`: generic driver error\n- `not_available`: integration not available yet\n- `not_connected`: the integration is not active on the file\n- `integration_inactive`: the integration is switched off\n- `no_driver`: nothing to run for this integration\n- `not_linked`: the file is not linked to the external system\n- `use_open_tab`: managed from its own tab (Peppol)\n- `file_required`: a file is expected\n- `file_too_large`: file above the size limit\n- `sync_failed`: the run failed\n- `novadesko_locked`: locked on the Novadesko side", "x-route-name": "api.v1.companies.integrations.config", "x-required-ability": "write", "x-demo-blocked": true, "x-error-codes": [ "integration_error", "not_available", "not_connected", "integration_inactive", "no_driver", "not_linked", "use_open_tab", "file_required", "file_too_large", "sync_failed", "novadesko_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "integration", "in": "path", "required": true, "description": "Slug of the integration (`novadesko`, `peppol`, `file_import`, …).", "schema": { "type": "string" }, "example": "novadesko" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "config": { "type": "object", "additionalProperties": true } }, "required": [ "config" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Integration" } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/integrations/{integration}/test": { "post": { "operationId": "companies.integrations.test", "tags": [ "Integrations" ], "summary": "Test the connection", "description": "Integration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 12 requests per minute (429 beyond, see `Retry-After`).\n\nError codes (`code`):\n- `integration_error`: generic driver error\n- `not_available`: integration not available yet\n- `not_connected`: the integration is not active on the file\n- `integration_inactive`: the integration is switched off\n- `no_driver`: nothing to run for this integration\n- `not_linked`: the file is not linked to the external system\n- `use_open_tab`: managed from its own tab (Peppol)\n- `file_required`: a file is expected\n- `file_too_large`: file above the size limit\n- `sync_failed`: the run failed\n- `novadesko_locked`: locked on the Novadesko side", "x-route-name": "api.v1.companies.integrations.test", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 12, "window_minutes": 1 }, "x-error-codes": [ "integration_error", "not_available", "not_connected", "integration_inactive", "no_driver", "not_linked", "use_open_tab", "file_required", "file_too_large", "sync_failed", "novadesko_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "integration", "in": "path", "required": true, "description": "Slug of the integration (`novadesko`, `peppol`, `file_import`, …).", "schema": { "type": "string" }, "example": "novadesko" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": [ "string", "null" ] }, "integration": { "$ref": "#/components/schemas/Integration" } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/integrations/{integration}/sync": { "post": { "operationId": "companies.integrations.sync", "tags": [ "Integrations" ], "summary": "Run a synchronisation", "description": "Runs the driver synchronously. JSON options (`full`) or, for `file_import`, a multipart upload (`file`: CODA, CSV…). On failure the answer is 422 with the last `run`.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 12 requests per minute (429 beyond, see `Retry-After`).\n\nError codes (`code`):\n- `integration_error`: generic driver error\n- `not_available`: integration not available yet\n- `not_connected`: the integration is not active on the file\n- `integration_inactive`: the integration is switched off\n- `no_driver`: nothing to run for this integration\n- `not_linked`: the file is not linked to the external system\n- `use_open_tab`: managed from its own tab (Peppol)\n- `file_required`: a file is expected\n- `file_too_large`: file above the size limit\n- `sync_failed`: the run failed\n- `novadesko_locked`: locked on the Novadesko side", "x-route-name": "api.v1.companies.integrations.sync", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 12, "window_minutes": 1 }, "x-error-codes": [ "integration_error", "not_available", "not_connected", "integration_inactive", "no_driver", "not_linked", "use_open_tab", "file_required", "file_too_large", "sync_failed", "novadesko_locked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "integration", "in": "path", "required": true, "description": "Slug of the integration (`novadesko`, `peppol`, `file_import`, …).", "schema": { "type": "string" }, "example": "novadesko" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "full": { "type": "boolean", "description": "Full resynchronisation instead of incremental." } } }, "example": { "full": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/IntegrationRun" }, "result": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Counters of the driver (documents, bank transactions, assets…)." }, "integration": { "$ref": "#/components/schemas/Integration" } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/integrations/{integration}/runs": { "get": { "operationId": "companies.integrations.runs", "tags": [ "Integrations" ], "summary": "Synchronisation runs", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.integrations.runs", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "integration", "in": "path", "required": true, "description": "Slug of the integration (`novadesko`, `peppol`, `file_import`, …).", "schema": { "type": "string" }, "example": "novadesko" }, { "name": "limit", "in": "query", "description": "1 to 100, 20 by default.", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationRun" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/integrations/{integration}/interest": { "post": { "operationId": "companies.integrations.interest", "tags": [ "Integrations" ], "summary": "Register an interest", "description": "For an integration that is not available yet (`coming_soon`).\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.", "x-route-name": "api.v1.companies.integrations.interest", "x-required-ability": "write", "x-demo-blocked": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "integration", "in": "path", "required": true, "description": "Slug of the integration (`novadesko`, `peppol`, `file_import`, …).", "schema": { "type": "string" }, "example": "novadesko" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "registered": { "type": "boolean" }, "registered_at": { "type": "string", "format": "date-time" }, "slug": { "type": "string", "example": "codabox" } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/sync/novadesko": { "post": { "operationId": "companies.sync.novadesko", "tags": [ "Integrations" ], "summary": "Synchronise the file from Novadesko", "description": "Reads documents, bank statements (CODA) and fixed assets of the linked shop. Read-only on the Novadesko side. 422 when the file is not linked or the integration is inactive.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 10 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.sync.novadesko", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 10, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "full": { "type": "boolean", "description": "Reload everything instead of the changes since the last run." } } }, "example": { "full": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "integer", "example": 12, "description": "Documents created or updated." }, "bank_transactions": { "type": "integer", "example": 34 }, "coda_files": { "type": "integer", "example": 2 }, "fixed_assets": { "type": "integer", "example": 0 }, "error": { "type": [ "string", "null" ] }, "synced_at": { "type": "string", "format": "date-time" } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/files/preview-url": { "get": { "operationId": "companies.files.preview-url", "tags": [ "Integrations" ], "summary": "Signed URL of a Novadesko file", "description": "Novadesko files cannot be framed directly; this returns a signed relay URL valid 20 minutes. Only whitelisted hosts and paths are relayed.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.files.preview-url", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "url", "in": "query", "required": true, "description": "File on web.novadesko.com.", "schema": { "type": "string", "format": "uri" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expires_in": { "type": "integer", "example": 1200 } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/files/view": { "get": { "operationId": "files.view", "tags": [ "Integrations" ], "summary": "Signed relay of a Novadesko file", "description": "Target of `files/preview-url`: serves the PDF or image inline with `frame-ancestors` allowing the app.\n\nAuthorised by the signature of the URL (query parameters `signature` and `expires`), not by a bearer token. The URL is issued by another endpoint and expires.\n\nRate limit: 120 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.files.view", "x-signed-url": true, "x-rate-limit": { "limit": 120, "window_minutes": 1 }, "security": [], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Expires" }, { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } } ], "responses": { "200": { "description": "The file, inline.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/history": { "get": { "operationId": "companies.history.index", "tags": [ "History & recycle bin" ], "summary": "Version history", "description": "Who changed what, from which device, newest first.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.history.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "subject_type", "in": "query", "description": "third_parties, accounts, journals, entries, documents, bank_transactions, fixed_assets…", "schema": { "type": "string" } }, { "name": "subject_id", "in": "query", "schema": { "type": "integer" } }, { "name": "user_id", "in": "query", "schema": { "type": "integer" } }, { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "created", "updated", "deleted", "restored", "reverted", "synced" ] } }, { "name": "origin", "in": "query", "schema": { "type": "string", "enum": [ "online", "offline_sync", "system", "bridge" ] } }, { "name": "operation_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "device_id", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "q", "in": "query", "description": "Record label, user or device.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/history/users": { "get": { "operationId": "companies.history.users", "tags": [ "History & recycle bin" ], "summary": "Filters of the history", "description": "People and devices that changed something, subject types and actions.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.history.users", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "example": "Claire Dumont" }, "revisions": { "type": "integer", "example": 214 }, "last_at": { "type": [ "string", "null" ], "format": "date-time" }, "role": { "type": "string", "example": "firm_admin" } } } }, "devices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "revisions": { "type": "integer" } } } }, "subject_types": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "third_parties" }, "label": { "type": "string", "example": "Tiers" } } } }, "actions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "created" }, "label": { "type": "string", "example": "Création" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/history/export": { "get": { "operationId": "companies.history.export", "tags": [ "History & recycle bin" ], "summary": "Export the history (CSV)", "description": "Same filters as the list. UTF-8 with BOM, semicolon separated.\n\nIntegration tokens need the `read` ability.\n\nRate limit: 30 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.history.export", "x-required-ability": "read", "x-rate-limit": { "limit": 30, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "subject_type", "in": "query", "description": "third_parties, accounts, journals, entries, documents, bank_transactions, fixed_assets…", "schema": { "type": "string" } }, { "name": "subject_id", "in": "query", "schema": { "type": "integer" } }, { "name": "user_id", "in": "query", "schema": { "type": "integer" } }, { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "created", "updated", "deleted", "restored", "reverted", "synced" ] } }, { "name": "origin", "in": "query", "schema": { "type": "string", "enum": [ "online", "offline_sync", "system", "bridge" ] } }, { "name": "operation_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "device_id", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "q", "in": "query", "description": "Record label, user or device.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "CSV file.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/history/settings": { "get": { "operationId": "companies.history.settings", "tags": [ "History & recycle bin" ], "summary": "Retention settings", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.history.settings", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "trash_retention_days": { "type": "integer", "example": 90 }, "default_trash_retention_days": { "type": "integer", "example": 90 }, "min_trash_retention_days": { "type": "integer", "example": 7 }, "max_trash_retention_days": { "type": "integer", "example": 3650 }, "sync_retention_days": { "type": "integer", "example": 90 }, "can_edit": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "companies.history.settings.update", "tags": [ "History & recycle bin" ], "summary": "Update the retention of the recycle bin", "description": "Managers only.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `settings_forbidden`: only a manager can change this setting", "x-route-name": "api.v1.companies.history.settings.update", "x-required-ability": "write", "x-error-codes": [ "settings_forbidden" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "trash_retention_days": { "type": "integer", "description": "7 to 3650." } }, "required": [ "trash_retention_days" ] }, "example": { "trash_retention_days": 180 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "trash_retention_days": { "type": "integer", "example": 180 }, "default_trash_retention_days": { "type": "integer", "example": 90 }, "min_trash_retention_days": { "type": "integer", "example": 7 }, "max_trash_retention_days": { "type": "integer", "example": 3650 }, "sync_retention_days": { "type": "integer", "example": 90 }, "can_edit": { "type": "boolean" } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/history/operations/{operation}/revert": { "post": { "operationId": "companies.history.operations.revert", "tags": [ "History & recycle bin" ], "summary": "Undo a whole operation", "description": "Reverts every change recorded under one `X-Operation-Id`, newest first, in one transaction: all or nothing.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `conflict`: the record changed since then (forceable by a manager with `force: true`)\n- `period_locked`: locked period or closed fiscal year\n- `vat_locked`: VAT return validated or submitted\n- `already_reverted`: already reverted\n- `not_revertible`: this kind of change cannot be reverted\n- `entry_immutable`: a posted entry is reversed, not modified\n- `in_use`: the record is in use\n- `booked`: the record is booked\n- `code_taken`: the code is used by another record\n- `force_forbidden`: only a manager can force\n- `read_only`: read-only access to the file\n- `operation_not_found`: unknown operation\n- `operation_not_revertible`: one change of the batch cannot be reverted\n- `nothing_to_revert`: nothing to revert", "x-route-name": "api.v1.companies.history.operations.revert", "x-required-ability": "write", "x-error-codes": [ "conflict", "period_locked", "vat_locked", "already_reverted", "not_revertible", "entry_immutable", "in_use", "booked", "code_taken", "force_forbidden", "read_only", "operation_not_found", "operation_not_revertible", "nothing_to_revert" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "operation", "in": "path", "required": true, "description": "Operation id (`X-Operation-Id`) grouping the changes of one action.", "schema": { "type": "string", "format": "uuid" }, "example": "bf413a19-2136-4504-bc42-b314637eb5c7" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ] }, "force": { "type": "boolean", "description": "Overwrite newer values (managers)." } } }, "example": { "reason": "Erreur de saisie" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reverted": { "type": "boolean" }, "operation_id": { "type": "string", "format": "uuid" }, "count": { "type": "integer", "example": 3 }, "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } }, "skipped": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/history/{revision}": { "get": { "operationId": "companies.history.show", "tags": [ "History & recycle bin" ], "summary": "Revision", "description": "With the snapshots before and after.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.history.show", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "revision", "in": "path", "required": true, "description": "Id of the revision (history line).", "schema": { "type": "integer" }, "example": 2301 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/history/{revision}/revert": { "post": { "operationId": "companies.history.revert", "tags": [ "History & recycle bin" ], "summary": "Revert a change", "description": "Puts back the state before the change: an update restores the previous values, a deletion restores the record, a creation sends it to the recycle bin, a posted entry is reversed. The revert is itself recorded and revertible.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `conflict`: the record changed since then (forceable by a manager with `force: true`)\n- `period_locked`: locked period or closed fiscal year\n- `vat_locked`: VAT return validated or submitted\n- `already_reverted`: already reverted\n- `not_revertible`: this kind of change cannot be reverted\n- `entry_immutable`: a posted entry is reversed, not modified\n- `in_use`: the record is in use\n- `booked`: the record is booked\n- `code_taken`: the code is used by another record\n- `force_forbidden`: only a manager can force\n- `read_only`: read-only access to the file\n- `operation_not_found`: unknown operation\n- `operation_not_revertible`: one change of the batch cannot be reverted\n- `nothing_to_revert`: nothing to revert", "x-route-name": "api.v1.companies.history.revert", "x-required-ability": "write", "x-error-codes": [ "conflict", "period_locked", "vat_locked", "already_reverted", "not_revertible", "entry_immutable", "in_use", "booked", "code_taken", "force_forbidden", "read_only", "operation_not_found", "operation_not_revertible", "nothing_to_revert" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "revision", "in": "path", "required": true, "description": "Id of the revision (history line).", "schema": { "type": "integer" }, "example": 2301 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ] }, "force": { "type": "boolean" } } }, "example": { "reason": "Mauvais tiers" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "reverted": { "type": "boolean" }, "effect": { "type": "string", "enum": [ "updated", "trashed", "restored", "recreated", "reversed" ] }, "revision_ids": { "type": "array", "items": { "type": "integer" } }, "subject_type": { "type": "string" }, "subject_id": { "type": "integer" }, "reversal_entry_id": { "type": [ "integer", "null" ] }, "revision": { "$ref": "#/components/schemas/Revision" }, "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/activity": { "get": { "operationId": "companies.activity", "tags": [ "History & recycle bin" ], "summary": "Activity of the file", "description": "Audit trail (sign-ins, exports, bookings…) and history merged, newest first. No total: use `has_more`.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.activity", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "user_id", "in": "query", "schema": { "type": "integer" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "audit", "revision" ] } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityFeed" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/trash": { "get": { "operationId": "companies.trash.index", "tags": [ "History & recycle bin" ], "summary": "Recycle bin", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.trash.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "type", "in": "query", "description": "Recycle bin type.", "schema": { "type": "string" } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TrashItem" } }, "counts": { "type": "object", "additionalProperties": true, "description": "Type => count." }, "types": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" } } } }, "total": { "type": "integer" }, "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "last_page": { "type": "integer" }, "retention_days": { "type": "integer", "example": 90 }, "can_purge": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/trash/restore-all": { "post": { "operationId": "companies.trash.restore-all", "tags": [ "History & recycle bin" ], "summary": "Restore everything", "description": "Optionally one type only.\n\nIntegration tokens need the `write` ability.", "x-route-name": "api.v1.companies.trash.restore-all", "x-required-ability": "write", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": [ "string", "null" ] } } }, "example": { "type": "third_parties" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "restored": { "type": "integer", "example": 4 }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer" }, "label": { "type": "string" }, "blocked_reason": { "type": "string", "example": "code_taken" } } } } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/trash/{type}/{id}/restore": { "post": { "operationId": "companies.trash.restore", "tags": [ "History & recycle bin" ], "summary": "Restore a record", "description": "A third party whose code was taken comes back with a suffixed code; an account, journal or analytic code is refused (`code_taken`).\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `code_taken`: the code is used by another record\n- `parent_missing`: the linked record no longer exists\n- `not_in_trash`: the record is not in the recycle bin\n- `restore_failed`: the restore failed", "x-route-name": "api.v1.companies.trash.restore", "x-required-ability": "write", "x-error-codes": [ "code_taken", "parent_missing", "not_in_trash", "restore_failed" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "type", "in": "path", "required": true, "description": "Recycle bin type: `third_parties`, `accounts`, `journals`, `journal_rules`, `bank_rules`, `recurring_entries`, `analytic_codes`, `fixed_assets`, `documents`, `document_imports`, `integrations`.", "schema": { "type": "string" }, "example": "third_parties" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "restored": { "type": "boolean" }, "type": { "type": "string" }, "id": { "type": "integer" }, "label": { "type": "string" }, "version": { "type": "integer" }, "data": { "type": "object", "additionalProperties": true } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/trash/{type}/{id}": { "delete": { "operationId": "companies.trash.purge", "tags": [ "History & recycle bin" ], "summary": "Delete definitively", "description": "Managers only; recorded in the audit trail. Cannot be undone.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `purge_forbidden`: only a manager can purge", "x-route-name": "api.v1.companies.trash.purge", "x-required-ability": "write", "x-error-codes": [ "purge_forbidden" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "type", "in": "path", "required": true, "description": "Recycle bin type: `third_parties`, `accounts`, `journals`, `journal_rules`, `bank_rules`, `recurring_entries`, `analytic_codes`, `fixed_assets`, `documents`, `document_imports`, `integrations`.", "schema": { "type": "string" }, "example": "third_parties" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "responses": { "204": { "description": "Done, no body.", "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-Trashed": { "$ref": "#/components/headers/X-Trashed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/companies/{company}/third-parties/{id}/history": { "get": { "operationId": "companies.history.subject.third-parties", "tags": [ "History & recycle bin" ], "summary": "History of one record (third parties)", "description": "Same items as the version history, limited to one record.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.history.subject.third-parties", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/entries/{id}/history": { "get": { "operationId": "companies.history.subject.entries", "tags": [ "History & recycle bin" ], "summary": "History of one record (entries)", "description": "Same items as the version history, limited to one record.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.history.subject.entries", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/documents/{id}/history": { "get": { "operationId": "companies.history.subject.documents", "tags": [ "History & recycle bin" ], "summary": "History of one record (documents)", "description": "Same items as the version history, limited to one record.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.history.subject.documents", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/accounts/{id}/history": { "get": { "operationId": "companies.history.subject.accounts", "tags": [ "History & recycle bin" ], "summary": "History of one record (accounts)", "description": "Same items as the version history, limited to one record.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.history.subject.accounts", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/bank-transactions/{id}/history": { "get": { "operationId": "companies.history.subject.bank-transactions", "tags": [ "History & recycle bin" ], "summary": "History of one record (bank transactions)", "description": "Same items as the version history, limited to one record.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.history.subject.bank-transactions", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/fixed-assets/{id}/history": { "get": { "operationId": "companies.history.subject.fixed-assets", "tags": [ "History & recycle bin" ], "summary": "History of one record (fixed assets)", "description": "Same items as the version history, limited to one record.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.history.subject.fixed-assets", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/journals/{id}/history": { "get": { "operationId": "companies.history.subject.journals", "tags": [ "History & recycle bin" ], "summary": "History of one record (journals)", "description": "Same items as the version history, limited to one record.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.history.subject.journals", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/recurring-entries/{id}/history": { "get": { "operationId": "companies.history.subject.recurring-entries", "tags": [ "History & recycle bin" ], "summary": "History of one record (recurring entries)", "description": "Same items as the version history, limited to one record.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.history.subject.recurring-entries", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/vat-declarations/{id}/history": { "get": { "operationId": "companies.history.subject.vat-declarations", "tags": [ "History & recycle bin" ], "summary": "History of one record (vat declarations)", "description": "Same items as the version history, limited to one record.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.companies.history.subject.vat-declarations", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/accounts/{id}": { "delete": { "operationId": "companies.trash.destroy.accounts", "tags": [ "History & recycle bin" ], "summary": "Move to the recycle bin (accounts)", "description": "Refused with 422 when the record is used or booked.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `in_use`: the record is used by entries or documents\n- `booked`: the record is booked: reverse the entry first", "x-route-name": "api.v1.companies.trash.destroy.accounts", "x-required-ability": "write", "x-error-codes": [ "in_use", "booked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "responses": { "204": { "description": "Done, no body.", "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-Trashed": { "$ref": "#/components/headers/X-Trashed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/analytic-codes/{id}": { "delete": { "operationId": "companies.trash.destroy.analytic-codes", "tags": [ "History & recycle bin" ], "summary": "Move to the recycle bin (analytic codes)", "description": "Refused with 422 when the record is used or booked.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `in_use`: the record is used by entries or documents\n- `booked`: the record is booked: reverse the entry first", "x-route-name": "api.v1.companies.trash.destroy.analytic-codes", "x-required-ability": "write", "x-error-codes": [ "in_use", "booked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "responses": { "204": { "description": "Done, no body.", "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-Trashed": { "$ref": "#/components/headers/X-Trashed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/fixed-assets/{id}": { "delete": { "operationId": "companies.trash.destroy.fixed-assets", "tags": [ "History & recycle bin" ], "summary": "Move to the recycle bin (fixed assets)", "description": "Refused with 422 when the record is used or booked.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `in_use`: the record is used by entries or documents\n- `booked`: the record is booked: reverse the entry first", "x-route-name": "api.v1.companies.trash.destroy.fixed-assets", "x-required-ability": "write", "x-error-codes": [ "in_use", "booked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "responses": { "204": { "description": "Done, no body.", "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-Trashed": { "$ref": "#/components/headers/X-Trashed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/documents/{id}": { "delete": { "operationId": "companies.trash.destroy.documents", "tags": [ "History & recycle bin" ], "summary": "Move to the recycle bin (documents)", "description": "Refused with 422 when the record is used or booked.\n\nIntegration tokens need the `write` ability.\n\nError codes (`code`):\n- `in_use`: the record is used by entries or documents\n- `booked`: the record is booked: reverse the entry first", "x-route-name": "api.v1.companies.trash.destroy.documents", "x-required-ability": "write", "x-error-codes": [ "in_use", "booked" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "id", "in": "path", "required": true, "description": "Id of the record.", "schema": { "type": "integer" }, "example": 42 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" }, { "$ref": "#/components/parameters/BaseVersion" } ], "responses": { "204": { "description": "Done, no body.", "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-Trashed": { "$ref": "#/components/headers/X-Trashed" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/sync/bootstrap": { "get": { "operationId": "companies.sync.bootstrap", "tags": [ "Synchronisation" ], "summary": "First load", "description": "Starting point of a local copy: the cursor, the list of resources with their REST endpoint, the company, its settings and the rights of the user. Load each resource through its endpoint, then keep `cursor` for `sync/pull`.\n\nIntegration tokens need the `sync` ability.", "x-route-name": "api.v1.companies.sync.bootstrap", "x-required-ability": "sync", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "cursor": { "type": "integer", "example": 1042 }, "server_time": { "type": "string", "format": "date-time" }, "full_resync": { "type": "boolean", "example": false }, "retention_days": { "type": "integer", "example": 90 }, "resources": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "third_parties" }, "count": { "type": "integer", "example": 187 }, "endpoint": { "type": "string", "example": "companies/XBVD5O1L29HC/third-parties" }, "paginated": { "type": "boolean", "example": false } } } }, "company": { "$ref": "#/components/schemas/Company" }, "company_settings": { "$ref": "#/components/schemas/CompanySettings" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "example": "Claire Dumont" }, "role": { "type": "string", "example": "firm_admin" }, "role_rank": { "type": "integer" }, "can_write": { "type": "boolean" }, "can_force": { "type": "boolean" } } }, "push": { "type": "object", "properties": { "resources": { "type": "array", "items": { "type": "string" } }, "max_mutations": { "type": "integer", "example": 200 }, "temp_id_prefix": { "type": "string", "example": "tmp-" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/sync/pull": { "get": { "operationId": "companies.sync.pull", "tags": [ "Synchronisation" ], "summary": "Incremental pull", "description": "Changes since a cursor, one line per record (last state). `delete` is a tombstone (deleted or in the recycle bin). When `since` is absent, unknown or older than the 90-day journal, `full_resync` is true and no change is returned: reload everything, then restart from the returned cursor. A change becomes visible two seconds after it was written.\n\nIntegration tokens need the `sync` ability.", "x-route-name": "api.v1.companies.sync.pull", "x-required-ability": "sync", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "since", "in": "query", "description": "Cursor of the previous pull or bootstrap.", "schema": { "type": "integer" }, "example": 1042 }, { "name": "resources", "in": "query", "description": "Comma-separated resource names.", "schema": { "type": "string" }, "example": "third_parties,entries" }, { "name": "limit", "in": "query", "description": "500 by default, 1000 max.", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "cursor": { "type": "integer", "example": 1057 }, "has_more": { "type": "boolean", "example": false }, "full_resync": { "type": "boolean", "example": false }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/SyncChange" } }, "server_time": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/sync/push": { "post": { "operationId": "companies.sync.push", "tags": [ "Synchronisation" ], "summary": "Push offline mutations", "description": "Up to 200 mutations, processed in order, each in its own transaction and replayed through the matching REST action. Idempotent on `client_mutation_id`. Conflicts are settled by the priority rules (posted or locked accounting data always wins; field-by-field merge; highest role, then most recent change).\n\nIntegration tokens need the `sync` ability.", "x-route-name": "api.v1.companies.sync.push", "x-required-ability": "sync", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "device": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string", "example": "macos" } } }, "mutations": { "type": "array", "items": { "$ref": "#/components/schemas/SyncMutation" } } }, "required": [ "mutations" ] }, "example": { "device": { "id": "erp-connector-01", "name": "ERP connector", "platform": "server" }, "mutations": [ { "client_mutation_id": "b0a6f6f0-7d1c-4c5e-8a55-3f2b1c9d0e11", "occurred_at": "2026-10-05T08:00:00Z", "resource": "third_parties", "op": "create", "client_temp_id": "tmp-3c1f", "data": { "type": "supplier", "name": "Proximus SA", "vat_number": "BE0202239951" } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SyncMutationResult" } }, "cursor": { "type": "integer" }, "server_time": { "type": "string", "format": "date-time" } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/sync/status": { "get": { "operationId": "companies.sync.status", "tags": [ "Synchronisation" ], "summary": "Synchronisation status", "description": "Integration tokens need the `sync` ability.", "x-route-name": "api.v1.companies.sync.status", "x-required-ability": "sync", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "cursor": { "type": "integer" }, "server_time": { "type": "string", "format": "date-time" }, "pending_conflicts": { "type": "integer", "example": 0 }, "last_push_at": { "type": [ "string", "null" ], "format": "date-time" }, "devices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "user": { "type": [ "object", "null" ], "additionalProperties": true }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_push_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_cursor": { "type": [ "integer", "null" ] } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/sync/conflicts": { "get": { "operationId": "companies.sync.conflicts", "tags": [ "Synchronisation" ], "summary": "Synchronisation conflicts", "description": "Integration tokens need the `sync` ability.", "x-route-name": "api.v1.companies.sync.conflicts", "x-required-ability": "sync", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "resolved" ] } }, { "name": "resource", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 50, maximum 200).", "schema": { "type": "integer" }, "example": 50 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SyncConflict" } }, "open": { "type": "integer", "example": 0, "description": "Number of open conflicts." } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/companies/{company}/sync/conflicts/{conflict}/resolve": { "post": { "operationId": "companies.sync.conflicts.resolve", "tags": [ "Synchronisation" ], "summary": "Resolve a conflict", "description": "`client` applies the values that were refused, `merge` applies `data`, `server` acknowledges.\n\nIntegration tokens need the `sync` ability.\n\nError codes (`code`):\n- `conflict_already_resolved`: already resolved\n- `conflict_choice_unavailable`: choice not available for this conflict", "x-route-name": "api.v1.companies.sync.conflicts.resolve", "x-required-ability": "sync", "x-error-codes": [ "conflict_already_resolved", "conflict_choice_unavailable" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "conflict", "in": "path", "required": true, "description": "Id of the synchronisation conflict.", "schema": { "type": "integer" }, "example": 8 }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "choice": { "type": "string", "enum": [ "server", "client", "merge" ] }, "data": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Required for `merge`." } }, "required": [ "choice" ] }, "example": { "choice": "client" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "resolved": { "type": "boolean" }, "conflict": { "$ref": "#/components/schemas/SyncConflict" }, "data": { "type": [ "object", "null" ], "additionalProperties": true } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/companies/{company}/mail/documents": { "post": { "operationId": "companies.mail.documents", "tags": [ "Mail" ], "summary": "Send documents or an export by e-mail", "description": "Sends documents of the file and / or an export to a client, in the name of the firm. Above 10 MB (or with `as_link`) the files are sent as a signed download link valid 7 days. Manager role at least.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 20 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.mail.documents", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 20, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email" } }, "cc": { "type": "array", "items": { "type": "string", "format": "email" } }, "subject": { "type": [ "string", "null" ] }, "message": { "type": "string", "description": "5000 characters max." }, "document_ids": { "type": "array", "items": { "type": "integer", "description": "Required without `export`." } }, "export": { "type": "object", "properties": { "type": { "type": "string", "description": "Export code or `full-dossier`." }, "format": { "type": "string", "enum": [ "pdf", "xlsx", "csv", "zip" ] }, "fiscal_year_id": { "type": [ "integer", "null" ] }, "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": [ "string", "null" ], "format": "date" }, "lang": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] }, "params": { "type": [ "object", "null" ], "additionalProperties": true } }, "required": [ "type" ] }, "as_link": { "type": "boolean" } }, "required": [ "to", "message" ] }, "example": { "to": [ "gerant@comptoir-montois.example" ], "subject": "Balance au 30 septembre", "message": "Bonjour, vous trouverez ci-joint la balance arrêtée au 30 septembre.", "export": { "type": "trial-balance", "format": "pdf", "to": "2026-09-30" } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "sent": { "type": "integer", "example": 1 }, "mode": { "type": "string", "enum": [ "attachment", "link" ] }, "recipients": { "type": "array", "items": { "type": "string", "format": "email" } }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "balance-2026-09-30.pdf" }, "size": { "type": "integer", "example": 48211 } } } }, "link_expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/mail/document-request": { "post": { "operationId": "companies.mail.document-request", "tags": [ "Mail" ], "summary": "Ask a client for missing documents", "description": "Integration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 20 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.companies.mail.document-request", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 20, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "$ref": "#/components/parameters/AcceptLanguage" }, { "$ref": "#/components/parameters/ClientMutationId" }, { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/DeviceId" }, { "$ref": "#/components/parameters/DeviceName" }, { "$ref": "#/components/parameters/OccurredAt" }, { "$ref": "#/components/parameters/Origin" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email" } }, "items": { "type": "array", "items": { "type": "string", "description": "One missing document per item." } }, "message": { "type": [ "string", "null" ] }, "due_date": { "type": [ "string", "null" ], "format": "date" } }, "required": [ "to", "items" ] }, "example": { "to": [ "gerant@comptoir-montois.example" ], "items": [ "Extrait bancaire de septembre", "Facture Engie d'août" ], "due_date": "2026-10-15" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "integer", "example": 1 }, "message": { "type": "string" } } } } }, "headers": { "X-Operation-Id": { "$ref": "#/components/headers/X-Operation-Id" }, "X-Idempotent-Replay": { "$ref": "#/components/headers/X-Idempotent-Replay" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/companies/{company}/mail/logs": { "get": { "operationId": "companies.mail.logs", "tags": [ "Mail" ], "summary": "Mails sent for the file", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.companies.mail.logs", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "company", "in": "path", "required": true, "description": "Public token of the company file (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "XBVD5O1L29HC" }, { "name": "template", "in": "query", "description": "Template key.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "25 by default, 100 max.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MailLog" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "total": { "type": "integer", "example": 12 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/mail/shares/{share}": { "get": { "operationId": "mail.shares.download", "tags": [ "Mail" ], "summary": "Download a shared file", "description": "Signed link of a mail (7 days). An expired or purged share redirects to the « download expired » page of the app.\n\nAuthorised by the signature of the URL (query parameters `signature` and `expires`), not by a bearer token. The URL is issued by another endpoint and expires.\n\nRate limit: 60 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.mail.shares.download", "x-signed-url": true, "x-rate-limit": { "limit": 60, "window_minutes": 1 }, "security": [], "parameters": [ { "name": "share", "in": "path", "required": true, "description": "Token of the shared file.", "schema": { "type": "string" }, "example": "q8ZrT2mVx4" }, { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Expires" } ], "responses": { "200": { "description": "The file.", "headers": { "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "302": { "description": "Expired share.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Target of the redirection." } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/mail/o/{token}.gif": { "get": { "operationId": "mail.open", "tags": [ "Mail" ], "summary": "Open pixel", "description": "Present in the mails only when tracking is switched on by the firm. Not meant to be called by integrations.\n\nPublic endpoint: no bearer token.\n\nRate limit: 240 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.mail.open", "x-rate-limit": { "limit": 240, "window_minutes": 1 }, "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Opaque token.", "schema": { "type": "string" }, "example": "a1B2c3D4e5" } ], "responses": { "200": { "description": "Transparent 1 × 1 GIF.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "image/gif": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/mail/c/{token}": { "get": { "operationId": "mail.click", "tags": [ "Mail" ], "summary": "Click redirection", "description": "Followed only when the signature of the target matches (no open redirect). Not meant to be called by integrations.\n\nPublic endpoint: no bearer token.\n\nRate limit: 240 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.mail.click", "x-rate-limit": { "limit": 240, "window_minutes": 1 }, "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Opaque token.", "schema": { "type": "string" }, "example": "a1B2c3D4e5" }, { "name": "u", "in": "query", "required": true, "description": "Encoded target.", "schema": { "type": "string" } }, { "name": "s", "in": "query", "required": true, "description": "Signature.", "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirection to the target.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" }, "description": "Target of the redirection." } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/webhooks/events": { "get": { "operationId": "webhooks.events", "tags": [ "Webhooks" ], "summary": "Catalogue of webhook events", "description": "Integration tokens need the `read` ability.", "x-route-name": "api.v1.webhooks.events", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string", "example": "entry.posted" }, "description": { "type": "string", "example": "An entry was posted." } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/firms/{firm}/webhooks": { "get": { "operationId": "firms.webhooks.index", "tags": [ "Webhooks" ], "summary": "List the webhook endpoints", "description": "Admins and managers of the firm (403 for other members, 404 for non-members).\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.firms.webhooks.index", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "available_events": { "type": "array", "items": { "type": "string", "example": "entry.posted", "description": "Event name." } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "operationId": "firms.webhooks.store", "tags": [ "Webhooks" ], "summary": "Create a webhook endpoint", "description": "The signing secret (`whsec_…`) is returned once. Events are queued and sent by a dispatcher that runs every minute.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nError codes (`code`):\n- `webhook_limit_reached`: 20 endpoints per firm at most\n- `webhook_url_refused`: the URL is not HTTPS or targets a private / loopback address (production)", "x-route-name": "api.v1.firms.webhooks.store", "x-required-ability": "write", "x-demo-blocked": true, "x-error-codes": [ "webhook_limit_reached", "webhook_url_refused" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint that receives the events (500 characters max)." }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string", "description": "Event name or `*`." } }, "is_active": { "type": "boolean" } }, "required": [ "url", "events" ] }, "example": { "url": "https://erp.example.com/hooks/novafisko", "description": "ERP connector", "events": [ "entry.posted", "document.booked", "vat.declaration_validated" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/WebhookEndpoint" }, "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "secret": { "type": "string", "example": "whsec_4Qm9x2kL8vT4nR7sW1pZ5cY3hJ6dF0gA9bE2uI4o", "description": "Signing secret (whsec_ followed by 40 characters), shown once." } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/v1/firms/{firm}/webhooks/{webhook}": { "patch": { "operationId": "firms.webhooks.update", "tags": [ "Webhooks" ], "summary": "Update a webhook endpoint", "description": "A paused endpoint keeps its pending deliveries; they are sent once it is active again.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nError codes (`code`):\n- `webhook_url_refused`: the URL is not HTTPS or targets a private / loopback address (production)", "x-route-name": "api.v1.firms.webhooks.update", "x-required-ability": "write", "x-demo-blocked": true, "x-error-codes": [ "webhook_url_refused" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "name": "webhook", "in": "path", "required": true, "description": "Id of the webhook endpoint.", "schema": { "type": "integer" }, "example": 3 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" } } }, "example": { "is_active": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/WebhookEndpoint" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "operationId": "firms.webhooks.destroy", "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "description": "Pending deliveries of the endpoint are dropped.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.", "x-route-name": "api.v1.firms.webhooks.destroy", "x-required-ability": "write", "x-demo-blocked": true, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "name": "webhook", "in": "path", "required": true, "description": "Id of the webhook endpoint.", "schema": { "type": "integer" }, "example": 3 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "204": { "description": "Done, no body." }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/firms/{firm}/webhooks/{webhook}/test": { "post": { "operationId": "firms.webhooks.test", "tags": [ "Webhooks" ], "summary": "Send a test event", "description": "Sends a `webhook.test` event immediately, signed like a real one. It is never retried: the returned delivery is `delivered` or `failed`.\n\nIntegration tokens need the `write` ability.\n\nNot available in demo mode: answers 403 `demo_mode`.\n\nRate limit: 12 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.firms.webhooks.test", "x-required-ability": "write", "x-demo-blocked": true, "x-rate-limit": { "limit": 12, "window_minutes": 1 }, "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "name": "webhook", "in": "path", "required": true, "description": "Id of the webhook endpoint.", "schema": { "type": "integer" }, "example": 3 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "202": { "description": "Test event sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "$ref": "#/components/schemas/WebhookDelivery" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/firms/{firm}/webhooks/{webhook}/deliveries": { "get": { "operationId": "firms.webhooks.deliveries", "tags": [ "Webhooks" ], "summary": "Deliveries of a webhook endpoint", "description": "Newest first, with the status, the number of attempts and an excerpt of the answer (2000 characters max). Deliveries that are no longer pending are pruned after 30 days.\n\nIntegration tokens need the `read` ability.", "x-route-name": "api.v1.firms.webhooks.deliveries", "x-required-ability": "read", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "firm", "in": "path", "required": true, "description": "Public token of the firm (`public_token`, 12 characters).", "schema": { "type": "string", "minLength": 12, "maxLength": 12 }, "example": "NDTQVQU4AUAV" }, { "name": "webhook", "in": "path", "required": true, "description": "Id of the webhook endpoint.", "schema": { "type": "integer" }, "example": 3 }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "delivered", "failed" ] } }, { "name": "event", "in": "query", "schema": { "type": "string" }, "example": "entry.posted" }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer" }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Items per page (default 25, maximum 100).", "schema": { "type": "integer" }, "example": 25 }, { "$ref": "#/components/parameters/AcceptLanguage" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 3 }, "per_page": { "type": "integer", "example": 25 }, "total": { "type": "integer", "example": 61 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/bridge/ping": { "get": { "operationId": "bridge.ping", "tags": [ "Novadesko bridge" ], "summary": "Ping of the Novadesko bridge", "description": "Used by Novadesko to check the shared secret. Reserved to the Novadesko platform.\n\nPublic endpoint: no bearer token.\n\nRate limit: 30 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.bridge.ping", "x-rate-limit": { "limit": 30, "window_minutes": 1 }, "security": [], "parameters": [ { "name": "X-Novafisko-Secret", "in": "header", "required": true, "description": "Shared secret of the bridge.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "app": { "type": "string", "example": "NovaFisko" }, "time": { "type": "string", "format": "date-time" }, "linked_firms": { "type": "integer" }, "linked_companies": { "type": "integer" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/v1/bridge/shops/{token}/status": { "get": { "operationId": "bridge.shop-status", "tags": [ "Novadesko bridge" ], "summary": "Synchronisation status of a Novadesko shop", "description": "Shown on the integration page of Novadesko. Reserved to the Novadesko platform (shared secret).\n\nPublic endpoint: no bearer token.\n\nRate limit: 60 requests per minute (429 beyond, see `Retry-After`).", "x-route-name": "api.v1.bridge.shop-status", "x-rate-limit": { "limit": 60, "window_minutes": 1 }, "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Token of the Novadesko shop.", "schema": { "type": "string" }, "example": "shp_8fK2mQ" }, { "name": "X-Novafisko-Secret", "in": "header", "required": true, "description": "Shared secret of the bridge.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "linked": { "type": "boolean" }, "company": { "type": "object", "additionalProperties": true }, "firm": { "type": "object", "additionalProperties": true }, "synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "documents": { "type": "object", "properties": { "total": { "type": "integer" }, "pending": { "type": "integer" }, "booked": { "type": "integer" }, "ignored": { "type": "integer" }, "by_type": { "type": "object", "additionalProperties": true } } }, "bank_transactions": { "type": "integer" }, "fixed_assets": { "type": "integer" }, "journal_entries": { "type": "integer" }, "corrections": { "type": "object", "properties": { "total": { "type": "integer" }, "recent": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "app_url": { "type": "string", "format": "uri" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "webhooks": { "document.imported": { "post": { "operationId": "webhook.document.imported", "tags": [ "Webhooks" ], "summary": "document.imported", "description": "A document entered the company file (Novadesko synchronisation or document importer).", "parameters": [ { "name": "X-Novafisko-Signature", "in": "header", "required": true, "description": "`t=,v1=.\")>`. Compare in constant time and refuse timestamps older than five minutes.", "schema": { "type": "string" }, "example": "t=1791189214,v1=5d2f0c9a7b6e4d1f8a3c2b1e0f9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c" }, { "name": "X-Novafisko-Event", "in": "header", "required": true, "description": "Event name.", "schema": { "type": "string" }, "example": "document.imported" }, { "name": "X-Novafisko-Delivery", "in": "header", "required": true, "description": "Id of the delivery (stable across retries).", "schema": { "type": "string" }, "example": "1871" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01JD8X5Q2M7Z4W9K3T6B0N1VCE", "event": "document.imported", "api_version": "v1", "created_at": "2026-10-05T08:21:48Z", "firm": { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés" }, "company": { "public_token": "XBVD5O1L29HC", "name": "Le Comptoir Montois SRL" }, "data": { "id": 87, "source": "novafisko", "origin": "novafisko", "type": "purchases", "direction": "purchase", "is_credit_note": false, "number": "F-2026-0412", "document_date": "2026-03-15", "due_date": "2026-04-14", "third_party_id": 18, "third_party_name": "Brasserie Dubuisson SA", "third_party_vat": "BE0402531376", "currency": "EUR", "amount_net": "542.00", "amount_vat": "113.82", "amount_gross": "655.82", "status": "pending", "journal_entry_id": null } } } } }, "responses": { "200": { "description": "Any 2xx answer within 10 seconds acknowledges the delivery. Anything else is retried with an exponential backoff (1, 2, 4, 8, 16, 32 and 64 minutes): 8 attempts, then the delivery is `failed`." } } } }, "document.booked": { "post": { "operationId": "webhook.document.booked", "tags": [ "Webhooks" ], "summary": "document.booked", "description": "A document was booked to an entry.", "parameters": [ { "name": "X-Novafisko-Signature", "in": "header", "required": true, "description": "`t=,v1=.\")>`. Compare in constant time and refuse timestamps older than five minutes.", "schema": { "type": "string" }, "example": "t=1791189214,v1=5d2f0c9a7b6e4d1f8a3c2b1e0f9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c" }, { "name": "X-Novafisko-Event", "in": "header", "required": true, "description": "Event name.", "schema": { "type": "string" }, "example": "document.booked" }, { "name": "X-Novafisko-Delivery", "in": "header", "required": true, "description": "Id of the delivery (stable across retries).", "schema": { "type": "string" }, "example": "1871" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01JD8X5Q2M7Z4W9K3T6B0N1VCE", "event": "document.booked", "api_version": "v1", "created_at": "2026-10-05T08:21:48Z", "firm": { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés" }, "company": { "public_token": "XBVD5O1L29HC", "name": "Le Comptoir Montois SRL" }, "data": { "id": 87, "source": "novafisko", "origin": "novafisko", "type": "purchases", "direction": "purchase", "is_credit_note": false, "number": "F-2026-0412", "document_date": "2026-03-15", "due_date": "2026-04-14", "third_party_id": 18, "third_party_name": "Brasserie Dubuisson SA", "third_party_vat": "BE0402531376", "currency": "EUR", "amount_net": "542.00", "amount_vat": "113.82", "amount_gross": "655.82", "status": "booked", "journal_entry_id": 1284 } } } } }, "responses": { "200": { "description": "Any 2xx answer within 10 seconds acknowledges the delivery. Anything else is retried with an exponential backoff (1, 2, 4, 8, 16, 32 and 64 minutes): 8 attempts, then the delivery is `failed`." } } } }, "entry.posted": { "post": { "operationId": "webhook.entry.posted", "tags": [ "Webhooks" ], "summary": "entry.posted", "description": "An entry was posted.", "parameters": [ { "name": "X-Novafisko-Signature", "in": "header", "required": true, "description": "`t=,v1=.\")>`. Compare in constant time and refuse timestamps older than five minutes.", "schema": { "type": "string" }, "example": "t=1791189214,v1=5d2f0c9a7b6e4d1f8a3c2b1e0f9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c" }, { "name": "X-Novafisko-Event", "in": "header", "required": true, "description": "Event name.", "schema": { "type": "string" }, "example": "entry.posted" }, { "name": "X-Novafisko-Delivery", "in": "header", "required": true, "description": "Id of the delivery (stable across retries).", "schema": { "type": "string" }, "example": "1871" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01JD8X5Q2M7Z4W9K3T6B0N1VCE", "event": "entry.posted", "api_version": "v1", "created_at": "2026-10-05T08:21:48Z", "firm": { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés" }, "company": { "public_token": "XBVD5O1L29HC", "name": "Le Comptoir Montois SRL" }, "data": { "id": 1284, "reference": "ACH 2026/000412", "journal_code": "ACH", "fiscal_year_code": "2026", "number": 412, "entry_date": "2026-03-15", "due_date": "2026-04-14", "label": "Facture Brasserie Dubuisson SA", "document_reference": "F-2026-0412", "status": "posted", "origin": "manual", "third_party_id": 18, "total_debit": "655.82", "total_credit": "655.82", "lines_count": 4, "reversed_entry_id": null, "reversed_by_entry_id": null } } } } }, "responses": { "200": { "description": "Any 2xx answer within 10 seconds acknowledges the delivery. Anything else is retried with an exponential backoff (1, 2, 4, 8, 16, 32 and 64 minutes): 8 attempts, then the delivery is `failed`." } } } }, "entry.reversed": { "post": { "operationId": "webhook.entry.reversed", "tags": [ "Webhooks" ], "summary": "entry.reversed", "description": "An entry was reversed; `reversed_by_entry_id` is the reversal entry.", "parameters": [ { "name": "X-Novafisko-Signature", "in": "header", "required": true, "description": "`t=,v1=.\")>`. Compare in constant time and refuse timestamps older than five minutes.", "schema": { "type": "string" }, "example": "t=1791189214,v1=5d2f0c9a7b6e4d1f8a3c2b1e0f9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c" }, { "name": "X-Novafisko-Event", "in": "header", "required": true, "description": "Event name.", "schema": { "type": "string" }, "example": "entry.reversed" }, { "name": "X-Novafisko-Delivery", "in": "header", "required": true, "description": "Id of the delivery (stable across retries).", "schema": { "type": "string" }, "example": "1871" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01JD8X5Q2M7Z4W9K3T6B0N1VCE", "event": "entry.reversed", "api_version": "v1", "created_at": "2026-10-05T08:21:48Z", "firm": { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés" }, "company": { "public_token": "XBVD5O1L29HC", "name": "Le Comptoir Montois SRL" }, "data": { "id": 1284, "reference": "ACH 2026/000412", "journal_code": "ACH", "fiscal_year_code": "2026", "number": 412, "entry_date": "2026-03-15", "due_date": "2026-04-14", "label": "Facture Brasserie Dubuisson SA", "document_reference": "F-2026-0412", "status": "reversed", "origin": "manual", "third_party_id": 18, "total_debit": "655.82", "total_credit": "655.82", "lines_count": 4, "reversed_entry_id": null, "reversed_by_entry_id": 1301 } } } } }, "responses": { "200": { "description": "Any 2xx answer within 10 seconds acknowledges the delivery. Anything else is retried with an exponential backoff (1, 2, 4, 8, 16, 32 and 64 minutes): 8 attempts, then the delivery is `failed`." } } } }, "bank.transaction_imported": { "post": { "operationId": "webhook.bank.transaction_imported", "tags": [ "Webhooks" ], "summary": "bank.transaction_imported", "description": "A bank transaction was imported (one event per transaction).", "parameters": [ { "name": "X-Novafisko-Signature", "in": "header", "required": true, "description": "`t=,v1=.\")>`. Compare in constant time and refuse timestamps older than five minutes.", "schema": { "type": "string" }, "example": "t=1791189214,v1=5d2f0c9a7b6e4d1f8a3c2b1e0f9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c" }, { "name": "X-Novafisko-Event", "in": "header", "required": true, "description": "Event name.", "schema": { "type": "string" }, "example": "bank.transaction_imported" }, { "name": "X-Novafisko-Delivery", "in": "header", "required": true, "description": "Id of the delivery (stable across retries).", "schema": { "type": "string" }, "example": "1871" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01JD8X5Q2M7Z4W9K3T6B0N1VCE", "event": "bank.transaction_imported", "api_version": "v1", "created_at": "2026-10-05T08:21:48Z", "firm": { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés" }, "company": { "public_token": "XBVD5O1L29HC", "name": "Le Comptoir Montois SRL" }, "data": { "id": 951, "source": "novadesko", "account_iban": "BE68539007547034", "value_date": "2026-03-18", "amount": "-655.82", "currency": "EUR", "counterpart_name": "Brasserie Dubuisson SA", "counterpart_iban": "BE71096123456769", "communication": "F-2026-0412", "status": "pending" } } } } }, "responses": { "200": { "description": "Any 2xx answer within 10 seconds acknowledges the delivery. Anything else is retried with an exponential backoff (1, 2, 4, 8, 16, 32 and 64 minutes): 8 attempts, then the delivery is `failed`." } } } }, "vat.declaration_validated": { "post": { "operationId": "webhook.vat.declaration_validated", "tags": [ "Webhooks" ], "summary": "vat.declaration_validated", "description": "A VAT declaration was validated and its settlement entry posted.", "parameters": [ { "name": "X-Novafisko-Signature", "in": "header", "required": true, "description": "`t=,v1=.\")>`. Compare in constant time and refuse timestamps older than five minutes.", "schema": { "type": "string" }, "example": "t=1791189214,v1=5d2f0c9a7b6e4d1f8a3c2b1e0f9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c" }, { "name": "X-Novafisko-Event", "in": "header", "required": true, "description": "Event name.", "schema": { "type": "string" }, "example": "vat.declaration_validated" }, { "name": "X-Novafisko-Delivery", "in": "header", "required": true, "description": "Id of the delivery (stable across retries).", "schema": { "type": "string" }, "example": "1871" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01JD8X5Q2M7Z4W9K3T6B0N1VCE", "event": "vat.declaration_validated", "api_version": "v1", "created_at": "2026-10-05T08:21:48Z", "firm": { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés" }, "company": { "public_token": "XBVD5O1L29HC", "name": "Le Comptoir Montois SRL" }, "data": { "id": 14, "period_type": "quarterly", "year": 2026, "period": 1, "label": "1T 2026", "starts_on": "2026-01-01", "ends_on": "2026-03-31", "amount_due": "157.50", "amount_refund": "0.00", "status": "validated", "validated_at": "2026-04-14T09:02:11Z", "journal_entry_id": 1420 } } } } }, "responses": { "200": { "description": "Any 2xx answer within 10 seconds acknowledges the delivery. Anything else is retried with an exponential backoff (1, 2, 4, 8, 16, 32 and 64 minutes): 8 attempts, then the delivery is `failed`." } } } }, "fiscal_year.closed": { "post": { "operationId": "webhook.fiscal_year.closed", "tags": [ "Webhooks" ], "summary": "fiscal_year.closed", "description": "A fiscal year was closed.", "parameters": [ { "name": "X-Novafisko-Signature", "in": "header", "required": true, "description": "`t=,v1=.\")>`. Compare in constant time and refuse timestamps older than five minutes.", "schema": { "type": "string" }, "example": "t=1791189214,v1=5d2f0c9a7b6e4d1f8a3c2b1e0f9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c" }, { "name": "X-Novafisko-Event", "in": "header", "required": true, "description": "Event name.", "schema": { "type": "string" }, "example": "fiscal_year.closed" }, { "name": "X-Novafisko-Delivery", "in": "header", "required": true, "description": "Id of the delivery (stable across retries).", "schema": { "type": "string" }, "example": "1871" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01JD8X5Q2M7Z4W9K3T6B0N1VCE", "event": "fiscal_year.closed", "api_version": "v1", "created_at": "2026-10-05T08:21:48Z", "firm": { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés" }, "company": { "public_token": "XBVD5O1L29HC", "name": "Le Comptoir Montois SRL" }, "data": { "id": 2, "code": "2025", "starts_on": "2025-01-01", "ends_on": "2025-12-31", "closed_at": "2026-05-28T14:30:00Z" } } } } }, "responses": { "200": { "description": "Any 2xx answer within 10 seconds acknowledges the delivery. Anything else is retried with an exponential backoff (1, 2, 4, 8, 16, 32 and 64 minutes): 8 attempts, then the delivery is `failed`." } } } }, "peppol.status_changed": { "post": { "operationId": "webhook.peppol.status_changed", "tags": [ "Webhooks" ], "summary": "peppol.status_changed", "description": "The Peppol registration of a company file changed status.", "parameters": [ { "name": "X-Novafisko-Signature", "in": "header", "required": true, "description": "`t=,v1=.\")>`. Compare in constant time and refuse timestamps older than five minutes.", "schema": { "type": "string" }, "example": "t=1791189214,v1=5d2f0c9a7b6e4d1f8a3c2b1e0f9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c" }, { "name": "X-Novafisko-Event", "in": "header", "required": true, "description": "Event name.", "schema": { "type": "string" }, "example": "peppol.status_changed" }, { "name": "X-Novafisko-Delivery", "in": "header", "required": true, "description": "Id of the delivery (stable across retries).", "schema": { "type": "string" }, "example": "1871" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01JD8X5Q2M7Z4W9K3T6B0N1VCE", "event": "peppol.status_changed", "api_version": "v1", "created_at": "2026-10-05T08:21:48Z", "firm": { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés" }, "company": { "public_token": "XBVD5O1L29HC", "name": "Le Comptoir Montois SRL" }, "data": { "id": 5, "participant_id": "0208:0477472701", "full_id": "iso6523-actorid-upis::0208:0477472701", "status": "active", "previous_status": "pending", "incoming_enabled": true, "activated_at": "2026-03-02T10:15:00Z" } } } } }, "responses": { "200": { "description": "Any 2xx answer within 10 seconds acknowledges the delivery. Anything else is retried with an exponential backoff (1, 2, 4, 8, 16, 32 and 64 minutes): 8 attempts, then the delivery is `failed`." } } } }, "third_party.created": { "post": { "operationId": "webhook.third_party.created", "tags": [ "Webhooks" ], "summary": "third_party.created", "description": "A customer or supplier was created.", "parameters": [ { "name": "X-Novafisko-Signature", "in": "header", "required": true, "description": "`t=,v1=.\")>`. Compare in constant time and refuse timestamps older than five minutes.", "schema": { "type": "string" }, "example": "t=1791189214,v1=5d2f0c9a7b6e4d1f8a3c2b1e0f9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c" }, { "name": "X-Novafisko-Event", "in": "header", "required": true, "description": "Event name.", "schema": { "type": "string" }, "example": "third_party.created" }, { "name": "X-Novafisko-Delivery", "in": "header", "required": true, "description": "Id of the delivery (stable across retries).", "schema": { "type": "string" }, "example": "1871" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01JD8X5Q2M7Z4W9K3T6B0N1VCE", "event": "third_party.created", "api_version": "v1", "created_at": "2026-10-05T08:21:48Z", "firm": { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés" }, "company": { "public_token": "XBVD5O1L29HC", "name": "Le Comptoir Montois SRL" }, "data": { "id": 18, "type": "supplier", "code": "DUBUISSON", "name": "Brasserie Dubuisson SA", "vat_number": "BE0402531376", "enterprise_number": "0402531376", "country": "BE", "email": "compta@dubuisson.example", "peppol_identifier": "0208:0402531376", "peppol_registered": true } } } } }, "responses": { "200": { "description": "Any 2xx answer within 10 seconds acknowledges the delivery. Anything else is retried with an exponential backoff (1, 2, 4, 8, 16, 32 and 64 minutes): 8 attempts, then the delivery is `failed`." } } } }, "third_party.updated": { "post": { "operationId": "webhook.third_party.updated", "tags": [ "Webhooks" ], "summary": "third_party.updated", "description": "A customer or supplier was updated; `changed` lists the columns.", "parameters": [ { "name": "X-Novafisko-Signature", "in": "header", "required": true, "description": "`t=,v1=.\")>`. Compare in constant time and refuse timestamps older than five minutes.", "schema": { "type": "string" }, "example": "t=1791189214,v1=5d2f0c9a7b6e4d1f8a3c2b1e0f9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c" }, { "name": "X-Novafisko-Event", "in": "header", "required": true, "description": "Event name.", "schema": { "type": "string" }, "example": "third_party.updated" }, { "name": "X-Novafisko-Delivery", "in": "header", "required": true, "description": "Id of the delivery (stable across retries).", "schema": { "type": "string" }, "example": "1871" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01JD8X5Q2M7Z4W9K3T6B0N1VCE", "event": "third_party.updated", "api_version": "v1", "created_at": "2026-10-05T08:21:48Z", "firm": { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés" }, "company": { "public_token": "XBVD5O1L29HC", "name": "Le Comptoir Montois SRL" }, "data": { "id": 18, "type": "supplier", "code": "DUBUISSON", "name": "Brasserie Dubuisson SA", "vat_number": "BE0402531376", "enterprise_number": "0402531376", "country": "BE", "email": "facturation@dubuisson.example", "peppol_identifier": "0208:0402531376", "peppol_registered": true, "changed": [ "email" ] } } } } }, "responses": { "200": { "description": "Any 2xx answer within 10 seconds acknowledges the delivery. Anything else is retried with an exponential backoff (1, 2, 4, 8, 16, 32 and 64 minutes): 8 attempts, then the delivery is `failed`." } } } }, "webhook.test": { "post": { "operationId": "webhook.webhook.test", "tags": [ "Webhooks" ], "summary": "webhook.test", "description": "Test event sent by `POST /v1/firms/{firm}/webhooks/{webhook}/test`; `company` is null.", "parameters": [ { "name": "X-Novafisko-Signature", "in": "header", "required": true, "description": "`t=,v1=.\")>`. Compare in constant time and refuse timestamps older than five minutes.", "schema": { "type": "string" }, "example": "t=1791189214,v1=5d2f0c9a7b6e4d1f8a3c2b1e0f9d8c7b6a5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c" }, { "name": "X-Novafisko-Event", "in": "header", "required": true, "description": "Event name.", "schema": { "type": "string" }, "example": "webhook.test" }, { "name": "X-Novafisko-Delivery", "in": "header", "required": true, "description": "Id of the delivery (stable across retries).", "schema": { "type": "string" }, "example": "1871" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01JD8X5Q2M7Z4W9K3T6B0N1VCE", "event": "webhook.test", "api_version": "v1", "created_at": "2026-10-05T08:21:48Z", "firm": { "public_token": "NDTQVQU4AUAV", "name": "Fiduciaire Dumont & Associés" }, "company": null, "data": { "message": "Test event from NovaFisko.", "webhook_id": 3 } } } } }, "responses": { "200": { "description": "Any 2xx answer within 10 seconds acknowledges the delivery. Anything else is retried with an exponential backoff (1, 2, 4, 8, 16, 32 and 64 minutes): 8 attempts, then the delivery is `failed`." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Sanctum token (|)", "description": "Laravel Sanctum personal access token sent as `Authorization: Bearer `.\n\n- **Session token**: `POST /v1/auth/login` (all abilities, bound to the user).\n- **Integration token**: `POST /v1/auth/tokens` with the abilities `read`, `write` and / or `sync`, an optional expiry, shown once.\n- **Demo token**: `POST /v1/auth/demo` (ephemeral user of the demo firm; external effects answer 403 `demo_mode`)." } }, "parameters": { "AcceptLanguage": { "name": "Accept-Language", "in": "header", "required": false, "description": "Language of the translated messages and labels (`fr`, `nl`, `en`, `de`). The language of the authenticated user wins when it is set; several endpoints also accept `?lang=`.", "schema": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] }, "example": "fr" }, "ClientMutationId": { "name": "X-Client-Mutation-Id", "in": "header", "required": false, "description": "Idempotence key chosen by the client (64 characters max, a UUID is recommended). A request replayed with the same key returns the memorised result with status 200 and `X-Idempotent-Replay: 1`; nothing is executed twice.", "schema": { "type": "string", "maxLength": 64 }, "example": "b0a6f6f0-7d1c-4c5e-8a55-3f2b1c9d0e11" }, "BaseVersion": { "name": "X-Base-Version", "in": "header", "required": false, "description": "Optimistic lock (opt-in): the `version` of the record the client last read. When the record moved on the server the answer is 409 `conflict` with `server_version` and `server_data`, and nothing is changed.", "schema": { "type": "integer" }, "example": 3 }, "OperationId": { "name": "X-Operation-Id", "in": "header", "required": false, "description": "UUID grouping every change of the request in the history (generated when absent). Returned in the response when something was recorded: it is the handle of « undo ».", "schema": { "type": "string", "format": "uuid" } }, "DeviceId": { "name": "X-Device-Id", "in": "header", "required": false, "description": "Stable id of the app install or of the integration (64 characters max). Shown in the history and in the synchronisation status.", "schema": { "type": "string", "maxLength": 64 }, "example": "erp-connector-01" }, "DeviceName": { "name": "X-Device-Name", "in": "header", "required": false, "description": "Readable device name, percent-encoded (120 characters max).", "schema": { "type": "string", "maxLength": 120 }, "example": "ERP%20connector" }, "OccurredAt": { "name": "X-Occurred-At", "in": "header", "required": false, "description": "ISO 8601 date of the action on the client. Bounded to ±24 h around the server time; used to rank conflicts.", "schema": { "type": "string", "format": "date-time" } }, "Origin": { "name": "X-Origin", "in": "header", "required": false, "description": "`offline_sync` when the request replays an action made offline.", "schema": { "type": "string", "enum": [ "offline_sync" ] } }, "Signature": { "name": "signature", "in": "query", "required": true, "description": "Signature of the URL (issued by the API).", "schema": { "type": "string" } }, "Expires": { "name": "expires", "in": "query", "required": false, "description": "Unix timestamp after which the signed URL is refused.", "schema": { "type": "integer" } } }, "headers": { "X-Operation-Id": { "description": "Operation id under which the changes of the request were recorded in the history. Present only when something was recorded.", "schema": { "type": "string", "format": "uuid" } }, "X-Trashed": { "description": "`1` when the DELETE moved the record to the recycle bin (restorable) instead of destroying it.", "schema": { "type": "string", "enum": [ "1" ] } }, "X-Idempotent-Replay": { "description": "`1` when the answer is the memorised result of a previous request carrying the same `X-Client-Mutation-Id`.", "schema": { "type": "string", "enum": [ "1" ] } }, "X-Export-Fingerprint": { "description": "SHA-256 of the exported data set: two exports of the same data carry the same fingerprint.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Content-Disposition": { "description": "File name of the download (`attachment; filename=\"…\"`) or `inline` for previews.", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Maximum number of requests in the current window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before the next attempt.", "schema": { "type": "integer" } } }, "responses": { "BadRequest": { "description": "Malformed request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Bad request." } } } }, "Unauthenticated": { "description": "Missing, invalid, revoked or expired bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Unauthenticated." } } } }, "Forbidden": { "description": "Authenticated but not allowed: role too low, missing token ability (`token_ability_missing`, `session_token_required`), demo restriction (`demo_mode`) or invalid URL signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "This token does not have the \"write\" ability.", "code": "token_ability_missing", "required_ability": "write" } } } }, "NotFound": { "description": "Unknown resource, or resource the user has no access to (a company file the user cannot see answers 404, never 403).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Not Found" } } } }, "Conflict": { "description": "Optimistic lock: the record changed on the server since the version sent in `X-Base-Version`. Nothing was modified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionConflict" }, "example": { "message": "Cet enregistrement a été modifié entre-temps.", "code": "conflict", "server_version": 4, "server_data": { "id": 18, "name": "Brasserie Dubuisson SA", "version": 4 } } } } }, "Gone": { "description": "The resource expired or was purged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Gone" } } } }, "ValidationError": { "description": "Validation failed or business rule refused the request. `errors` maps each field to its messages; `code` is present when the refusal has a machine reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Le champ date de l'écriture est obligatoire.", "errors": { "entry_date": [ "Le champ date de l'écriture est obligatoire." ] } } } } }, "PeriodLockedOrValidationError": { "description": "Validation failed, or the write was refused because its period is locked or its fiscal year is closed (`code: period_locked`, with `reason`).", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PeriodLockedError" }, { "$ref": "#/components/schemas/Error" } ] }, "example": { "message": "La période Mars 2026 est verrouillée.", "code": "period_locked", "reason": "period_locked", "errors": { "entry_date": [ "La période Mars 2026 est verrouillée." ] } } } } }, "TooManyRequests": { "description": "Rate limit reached.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Too Many Attempts." } } } }, "ServiceUnavailable": { "description": "Temporarily unavailable (maintenance, external provider down). A 503 always carries a `code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Service unavailable", "code": "service_unavailable" } } } } }, "schemas": { "Account": { "type": "object", "properties": { "id": { "type": "integer", "example": 580 }, "company_id": { "type": "integer", "example": 7 }, "number": { "type": "string", "example": "702000", "description": "PCMN account number (2 to 12 digits)." }, "label": { "type": "string", "example": "Prestations de services" }, "type": { "type": "string", "enum": [ "asset", "liability", "expense", "income", "off_balance" ] }, "is_postable": { "type": "boolean", "description": "False for heading accounts." }, "is_reconcilable": { "type": "boolean", "description": "Lettering allowed (customers, suppliers…)." }, "purchase_grid": { "type": [ "integer", "null" ], "example": 82, "description": "VAT grid of purchases: 81, 82 or 83." }, "default_vat_code_id": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set while the record is in the recycle bin." }, "deleted_by": { "type": [ "integer", "null" ] }, "default_vat_code": { "type": [ "object", "null" ], "additionalProperties": true } } }, "ActivityFeed": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityRow" } }, "current_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "has_more": { "type": "boolean" } } }, "ActivityRow": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "audit", "revision" ] }, "at": { "type": "string", "format": "date-time" }, "recorded_at": { "type": "string", "format": "date-time" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "example": 12, "description": "User id" }, "name": { "type": "string", "example": "Claire Dumont", "description": "Name" } } }, { "type": "null" } ] }, "action": { "type": "string", "example": "entry.posted" }, "action_label": { "type": "string", "example": "Écriture validée" }, "subject_type": { "type": [ "string", "null" ] }, "subject_id": { "type": [ "integer", "null" ] }, "subject_label": { "type": [ "string", "null" ] }, "origin": { "type": [ "string", "null" ] }, "device_name": { "type": [ "string", "null" ] }, "revision_id": { "type": [ "integer", "null" ] }, "operation_id": { "type": [ "string", "null" ] }, "company_id": { "type": [ "integer", "null" ] }, "changed_fields": { "type": "array", "items": { "type": "string" } }, "company": { "type": [ "object", "null" ], "description": "Firm feed only.", "properties": { "token": { "type": "string" }, "name": { "type": "string" } } } } }, "AnalyticCode": { "type": "object", "properties": { "id": { "type": "integer", "example": 2 }, "company_id": { "type": "integer" }, "axis": { "type": "string", "enum": [ "cost_center", "project" ] }, "code": { "type": "string", "example": "SALLE" }, "label": { "type": "string", "example": "Salle" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set while the record is in the recycle bin." }, "deleted_by": { "type": [ "integer", "null" ] } } }, "BankRule": { "type": "object", "properties": { "id": { "type": "integer", "example": 6 }, "company_id": { "type": "integer" }, "name": { "type": "string", "example": "Frais bancaires" }, "field": { "type": "string", "enum": [ "counterpart_name", "counterpart_iban", "communication", "description", "any" ] }, "operator": { "type": "string", "enum": [ "contains", "equals", "starts" ] }, "pattern": { "type": "string", "example": "frais de tenue" }, "direction": { "type": "string", "enum": [ "in", "out", "any" ] }, "account_id": { "type": "integer", "example": 517 }, "third_party_id": { "type": [ "integer", "null" ] }, "label": { "type": [ "string", "null" ] }, "priority": { "type": "integer", "example": 100 }, "is_active": { "type": "boolean" }, "applied_count": { "type": "integer", "example": 14 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set while the record is in the recycle bin." }, "deleted_by": { "type": [ "integer", "null" ] }, "account": { "type": "object", "properties": { "id": { "type": "integer", "example": 580, "description": "Id" }, "number": { "type": "string", "example": "702000", "description": "Account number" }, "label": { "type": "string", "example": "Prestations de services", "description": "Label" } } }, "third_party": { "type": [ "object", "null" ], "additionalProperties": true } } }, "BankTransaction": { "type": "object", "properties": { "id": { "type": "integer", "example": 951 }, "company_id": { "type": "integer", "example": 7 }, "source": { "type": "string", "example": "novadesko" }, "external_id": { "type": [ "string", "null" ] }, "account_iban": { "type": "string", "example": "BE68539007547034" }, "account_bank": { "type": [ "string", "null" ] }, "journal_id": { "type": [ "integer", "null" ], "example": 7 }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1210.00", "description": "Positive = money in, negative = money out." }, "currency": { "type": "string", "example": "EUR" }, "value_date": { "type": "string", "format": "date-time", "example": "2026-03-18T00:00:00.000000Z" }, "execution_date": { "type": [ "string", "null" ], "format": "date-time" }, "counterpart_name": { "type": [ "string", "null" ], "example": "ACME SA" }, "counterpart_iban": { "type": [ "string", "null" ] }, "communication": { "type": [ "string", "null" ], "example": "+++000/0000/00101+++" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "booked", "ignored" ] }, "journal_entry_id": { "type": [ "integer", "null" ] }, "matched_journal_entry_id": { "type": [ "integer", "null" ], "description": "Invoice proposed by the matching." }, "match_confidence": { "type": [ "string", "null" ], "example": "high", "description": "high, medium or low." }, "match_reason": { "type": [ "string", "null" ], "example": "structured_communication", "description": "structured_communication, novadesko_link, amount_and_third_party, rule…" }, "matched_at": { "type": [ "string", "null" ], "format": "date-time" }, "booked_account_id": { "type": [ "integer", "null" ] }, "matched_rule_id": { "type": [ "integer", "null" ] }, "synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "journal": { "type": [ "object", "null" ], "additionalProperties": true }, "links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "matched_entry": { "type": [ "object", "null" ], "additionalProperties": true }, "booked_account": { "type": [ "object", "null" ], "additionalProperties": true }, "matched_rule": { "type": [ "object", "null" ], "additionalProperties": true }, "journal_entry": { "type": [ "object", "null" ], "additionalProperties": true } } }, "Budget": { "type": "object", "properties": { "id": { "type": "integer" }, "company_id": { "type": "integer" }, "fiscal_year_id": { "type": "integer" }, "scenario": { "type": "string", "example": "default" }, "account_id": { "type": "integer" }, "cost_center_id": { "type": [ "integer", "null" ] }, "period_number": { "type": "integer", "example": 3 }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1500.00" }, "account": { "type": "object", "properties": { "id": { "type": "integer", "example": 580, "description": "Id" }, "number": { "type": "string", "example": "702000", "description": "Account number" }, "label": { "type": "string", "example": "Prestations de services", "description": "Label" } } } } }, "CodaFile": { "type": "object", "properties": { "id": { "type": "integer", "example": 31 }, "company_id": { "type": "integer" }, "source": { "type": "string", "example": "novadesko" }, "external_id": { "type": [ "string", "null" ] }, "filename": { "type": "string", "example": "CODA_2026_031.cod" }, "source_url": { "type": [ "string", "null" ], "format": "uri" }, "account_iban": { "type": "string", "example": "BE68539007547034" }, "account_bank": { "type": [ "string", "null" ] }, "journal_id": { "type": [ "integer", "null" ] }, "statement_number": { "type": [ "string", "null" ], "example": "031" }, "sequence": { "type": [ "string", "null" ] }, "opening_balance": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$", "example": "18420.11" }, "closing_balance": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$", "example": "19630.11" }, "period_from": { "type": [ "string", "null" ], "format": "date-time" }, "period_to": { "type": [ "string", "null" ], "format": "date-time" }, "transactions_count": { "type": "integer", "example": 12 }, "status": { "type": "string", "example": "imported" }, "synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "journal": { "type": [ "object", "null" ], "additionalProperties": true } } }, "Company": { "description": "Company file (dossier). Addressed everywhere by its `public_token`.", "type": "object", "properties": { "id": { "type": "integer", "example": 7 }, "public_token": { "type": "string", "minLength": 12, "maxLength": 12, "example": "XBVD5O1L29HC" }, "firm_id": { "type": [ "integer", "null" ], "example": 3 }, "code": { "type": [ "string", "null" ], "example": "COMPTOIR" }, "name": { "type": "string", "example": "Le Comptoir Montois SRL" }, "legal_form": { "type": [ "string", "null" ], "example": "SRL" }, "legal_form_code": { "type": [ "string", "null" ], "example": "610", "description": "KBO / BCE legal form code." }, "enterprise_number": { "type": [ "string", "null" ], "example": "0477472701" }, "vat_number": { "type": [ "string", "null" ], "example": "BE0477472701" }, "country_pack": { "type": "string", "enum": [ "BE", "FR", "LU" ] }, "vat_regime": { "type": "string", "enum": [ "monthly", "quarterly", "franchise", "exempt", "unit" ] }, "currency": { "type": "string", "example": "EUR" }, "locale": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] }, "address": { "type": [ "string", "null" ], "example": "Grand-Place 14, 7000 Mons" }, "street": { "type": [ "string", "null" ], "example": "Grand-Place", "description": "Street" }, "house_number": { "type": [ "string", "null" ], "example": "14", "description": "Number" }, "box": { "type": [ "string", "null" ], "description": "Box" }, "postal_code": { "type": [ "string", "null" ], "example": "7000", "description": "Postal code" }, "city": { "type": [ "string", "null" ], "example": "Mons", "description": "City" }, "country": { "type": [ "string", "null" ], "example": "BE", "description": "ISO 3166-1 alpha-2" }, "latitude": { "type": [ "string", "null" ], "example": "50.4541000" }, "longitude": { "type": [ "string", "null" ], "example": "3.9523000" }, "nace_codes": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "code": { "type": "string", "example": "56111" }, "classification": { "type": "string", "enum": [ "MAIN", "SECO", "ANCI" ] } } } }, "main_nace_code": { "type": [ "string", "null" ], "example": "56111" }, "company_sheet_at": { "type": [ "string", "null" ], "format": "date-time" }, "logo_url": { "type": [ "string", "null" ], "format": "uri" }, "icon_url": { "type": [ "string", "null" ], "format": "uri" }, "fiscal_year_start": { "type": [ "string", "null" ], "format": "date" }, "fiscal_year_end": { "type": [ "string", "null" ], "format": "date" }, "settings": { "$ref": "#/components/schemas/CompanySettings" }, "is_active": { "type": "boolean" }, "is_demo": { "type": "boolean", "example": false, "description": "True for the company files of the demo firm." }, "source": { "type": "string", "enum": [ "manual", "novadesko" ] }, "external_id": { "type": [ "string", "null" ] }, "synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "journal_entries_count": { "type": "integer", "example": 1284, "description": "Present on list / show." }, "firm": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 }, "public_token": { "type": "string", "minLength": 12, "maxLength": 12, "example": "NDTQVQU4AUAV" }, "name": { "type": "string", "example": "Fiduciaire Dumont & Associés" } } }, "fiscal_years": { "type": "array", "items": { "$ref": "#/components/schemas/FiscalYear" } }, "journals": { "type": "array", "items": { "$ref": "#/components/schemas/Journal" } } } }, "CompanySettings": { "description": "Resolved settings of the company file (country pack defaults merged with the saved values).", "type": "object", "properties": { "vat": { "type": "object", "properties": { "administration_cell": { "type": [ "string", "null" ] }, "structured_communication": { "type": [ "string", "null" ] }, "directorate_number": { "type": [ "string", "null" ] }, "office_number": { "type": [ "string", "null" ] }, "declarant": { "type": "object", "properties": { "applicable": { "type": "boolean", "example": false }, "company_name": { "type": [ "string", "null" ] }, "signatory_1": { "type": [ "string", "null" ] }, "signatory_1_title": { "type": [ "string", "null" ] }, "signatory_2": { "type": [ "string", "null" ] }, "signatory_2_title": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "fax": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "language": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] } } }, "sender_281_50": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "enterprise_number": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" } } }, "filer": { "type": "object", "properties": { "quality": { "type": "string", "enum": [ "company", "accountant" ] }, "name": { "type": [ "string", "null" ] }, "enterprise_number": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" } } } } }, "legal": { "type": "object", "properties": { "rpm_district": { "type": [ "string", "null" ], "example": "Hainaut, division Mons", "description": "RPM / RPR district printed on legal documents." } } }, "annual_accounts": { "type": "object", "properties": { "scheme": { "type": "string", "enum": [ "abbreviated", "micro" ] }, "general_meeting_date": { "type": [ "string", "null" ], "format": "date" }, "directors": { "type": [ "string", "null" ] }, "valuation_rules": { "type": [ "string", "null" ] } } }, "auto_entries": { "type": "object", "properties": { "vat": { "type": "object", "properties": { "payable_account": { "type": "string", "example": "451000" }, "receivable_account": { "type": "string", "example": "411000" }, "correction_payable_account": { "type": [ "string", "null" ] }, "correction_receivable_account": { "type": [ "string", "null" ] }, "journal_id": { "type": [ "integer", "null" ] } } }, "invoices_to_receive": { "type": "object", "properties": { "supplier_account": { "type": "string", "example": "444000" }, "customer_account": { "type": "string", "example": "404000" }, "journal_id": { "type": [ "integer", "null" ] } } }, "reconciliation_difference": { "type": "object", "properties": { "expense_account": { "type": "string", "example": "657000" }, "income_account": { "type": "string", "example": "757000" }, "max_amount": { "type": "number", "example": 1 } } }, "transfers": { "type": "object", "properties": { "transit_account": { "type": "string", "example": "580000" }, "journal_id": { "type": [ "integer", "null" ] } } } } }, "history": { "type": "object", "properties": { "trash_retention_days": { "type": "integer", "example": 90 } } } } }, "CompanySheet": { "description": "Normalised company sheet (CompanySearch for BE / FR, VIES elsewhere).", "type": "object", "properties": { "identifier": { "type": "string", "example": "0477472701" }, "enterprise_number": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ], "example": "BE0477472701" }, "name": { "type": "string", "example": "Le Comptoir Montois" }, "legal_form": { "type": [ "string", "null" ], "example": "SRL" }, "legal_form_code": { "type": [ "string", "null" ], "example": "610" }, "status": { "type": [ "string", "null" ], "example": "active" }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "address": { "type": "object", "properties": { "street": { "type": [ "string", "null" ], "example": "Grand-Place", "description": "Street" }, "house_number": { "type": [ "string", "null" ], "example": "14", "description": "Number" }, "box": { "type": [ "string", "null" ], "description": "Box" }, "postal_code": { "type": [ "string", "null" ], "example": "7000", "description": "Postal code" }, "city": { "type": [ "string", "null" ], "example": "Mons", "description": "City" }, "country": { "type": [ "string", "null" ], "example": "BE", "description": "ISO 3166-1 alpha-2" } } }, "address_line": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "nace_codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "56111" }, "classification": { "type": "string", "enum": [ "MAIN", "SECO", "ANCI" ] }, "label": { "type": [ "string", "null" ] } } } }, "main_nace_code": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "source": { "type": "string", "example": "companysearch" }, "fetched_at": { "type": [ "string", "null" ], "format": "date-time" }, "map": { "type": "object", "properties": { "query": { "type": "string", "example": "Grand-Place 14, 7000 Mons, Belgique", "description": "Address used for the map" }, "apple_url": { "type": "string", "format": "uri" }, "google_url": { "type": "string", "format": "uri" }, "static_url": { "type": [ "string", "null" ], "format": "uri" }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] } } } } }, "DepreciationLine": { "type": "object", "properties": { "id": { "type": "integer" }, "fixed_asset_id": { "type": "integer", "example": 9 }, "year": { "type": "integer", "example": 2026 }, "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" }, "amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "2269.37" }, "cumulative_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "2269.37" }, "remaining_value": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "10130.63" }, "status": { "type": "string", "enum": [ "planned", "booked" ] }, "journal_entry_id": { "type": [ "integer", "null" ] }, "booked_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" } } }, "DocumentImport": { "description": "File uploaded to the document importer and its analysis.", "type": "object", "properties": { "id": { "type": "integer", "example": 311 }, "company_id": { "type": "integer", "example": 7 }, "uploaded_by": { "type": [ "integer", "null" ] }, "batch_id": { "type": "string", "format": "uuid", "description": "Groups the files of one upload." }, "parent_import_id": { "type": [ "integer", "null" ], "description": "ZIP the file was extracted from." }, "original_name": { "type": "string", "example": "facture-dubuisson-0412.pdf" }, "mime": { "type": "string", "example": "application/pdf" }, "size": { "type": "integer", "example": 184320, "description": "Bytes." }, "file_hash": { "type": "string", "description": "SHA-256, used to detect duplicates." }, "kind": { "type": "string", "enum": [ "pdf", "image", "xml", "zip", "other" ] }, "status": { "type": "string", "enum": [ "queued", "analyzing", "ready", "needs_review", "validated", "error", "duplicate", "expanded" ] }, "progress": { "type": "integer", "example": 100, "description": "0 to 100." }, "step": { "type": "string", "enum": [ "upload", "text", "ai", "lines", "match", "done" ] }, "engine": { "type": [ "string", "null" ], "example": "api", "description": "Engine that read the file." }, "extracted": { "anyOf": [ { "$ref": "#/components/schemas/ExtractedDocument" }, { "type": "null" } ] }, "raw_text": { "type": [ "string", "null" ], "description": "Text layer (absent from lists)." }, "warnings": { "type": [ "array", "null" ], "items": { "type": "string" } }, "error": { "type": [ "string", "null" ] }, "suggested_third_party_id": { "type": [ "integer", "null" ] }, "suggested_direction": { "type": [ "string", "null" ] }, "duplicate_of_import_id": { "type": [ "integer", "null" ] }, "duplicate_of_document_id": { "type": [ "integer", "null" ] }, "imported_document_id": { "type": [ "integer", "null" ], "description": "Document created by the validation." }, "novadesko_document_id": { "type": [ "string", "null" ] }, "novadesko_locked_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set while the record is in the recycle bin." }, "deleted_by": { "type": [ "integer", "null" ] }, "suggested_third_party": { "type": [ "object", "null" ], "additionalProperties": true } } }, "Error": { "description": "Error envelope. `message` is translated; `code` is a stable machine reason when the refusal has one; `errors` maps fields to messages (422).", "type": "object", "properties": { "message": { "type": "string", "example": "Le champ date de l'écriture est obligatoire.", "description": "Human-readable message (translated)." }, "code": { "type": "string", "example": "period_locked", "description": "Machine reason (`token_ability_missing`, `session_token_required`, `demo_mode`, `conflict`, `period_locked`, `company_limit_reached`, `service_unavailable`…)." }, "errors": { "type": "object", "description": "Field => list of messages.", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "entry_date": [ "La période Mars 2026 est verrouillée." ] } } }, "required": [ "message" ] }, "ExtractedDocument": { "description": "Data read from an uploaded file (AI extraction or UBL / CII parsing), editable before validation.", "type": "object", "properties": { "direction": { "type": "string", "enum": [ "purchase", "sale" ] }, "is_credit_note": { "type": "boolean", "example": false }, "number": { "type": [ "string", "null" ], "example": "F-2026-0412" }, "document_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "currency": { "type": "string", "example": "EUR" }, "supplier": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "example": "Brasserie Dubuisson SA" }, "vat_number": { "type": [ "string", "null" ], "example": "BE0402531376" }, "enterprise_number": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "iban": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } } }, "customer": { "type": [ "object", "null" ], "additionalProperties": true }, "amount_net": { "type": [ "string", "null" ], "example": "507.00" }, "amount_vat": { "type": [ "string", "null" ], "example": "106.47" }, "amount_gross": { "type": [ "string", "null" ], "example": "613.47" }, "structured_communication": { "type": [ "string", "null" ] }, "confidence": { "type": "number", "example": 0.93, "description": "0 to 1; below 0.6 the import needs a review." }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "example": "Fûts Bush Caractère 20 L" }, "quantity": { "type": [ "number", "null" ], "example": 6 }, "unit_price": { "type": [ "number", "null" ], "example": 84.5 }, "tax_rate": { "type": [ "number", "null" ], "example": 21 }, "amount_net": { "type": "string", "example": "507.00" }, "amount_vat": { "type": [ "string", "null" ], "example": "106.47" }, "account_id": { "type": [ "integer", "null" ], "description": "Suggested account." }, "account_number": { "type": [ "string", "null" ], "example": "604000" }, "vat_code_id": { "type": [ "integer", "null" ] }, "vat_code": { "type": [ "string", "null" ], "example": "A21" } } } } } }, "Firm": { "description": "Accounting firm (fiduciary) with its team and company files.", "type": "object", "properties": { "public_token": { "type": "string", "minLength": 12, "maxLength": 12, "example": "NDTQVQU4AUAV" }, "name": { "type": "string", "example": "Fiduciaire Dumont & Associés" }, "enterprise_number": { "type": [ "string", "null" ], "example": "0458662817" }, "vat_number": { "type": [ "string", "null" ], "example": "BE0458662817" }, "itaa_number": { "type": [ "string", "null" ], "example": "50.123.456", "description": "ITAA membership number." }, "itaa_status": { "type": [ "string", "null" ] }, "itaa_quality": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ], "example": "Rue de Nimy 52" }, "postal_code": { "type": [ "string", "null" ], "example": "7000" }, "city": { "type": [ "string", "null" ], "example": "Mons" }, "website": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ], "format": "uri" }, "is_partner": { "type": "boolean" }, "country_code": { "type": "string", "example": "BE" }, "locale": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "local", "novadesko" ] }, "synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "can_manage": { "type": "boolean", "description": "True for admins and managers of the firm." }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/FirmMember" } }, "companies": { "type": "array", "items": { "type": "object", "properties": { "public_token": { "type": "string", "minLength": 12, "maxLength": 12 }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "icon_url": { "type": [ "string", "null" ], "format": "uri" }, "logo_url": { "type": [ "string", "null" ], "format": "uri" }, "members": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "example": "Thomas Peeters" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "manager", "encoder", "reviewer" ] }, "is_active": { "type": "boolean" } } } } } } } } }, "FirmMember": { "type": "object", "properties": { "id": { "type": "integer", "example": 12 }, "name": { "type": "string", "example": "Thomas Peeters" }, "email": { "type": "string", "format": "email", "example": "thomas.peeters@fiduciaire-dumont.be" }, "auth_source": { "type": "string", "enum": [ "local", "novadesko" ] }, "locale": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] }, "role": { "type": "string", "enum": [ "admin", "manager", "encoder", "reviewer" ] }, "is_active": { "type": "boolean" }, "all_companies": { "type": "boolean", "description": "Admins and managers see every company file of the firm." }, "companies": { "type": "array", "items": { "type": "object", "properties": { "public_token": { "type": "string", "minLength": 12, "maxLength": 12 }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "manager", "encoder", "reviewer" ] }, "is_active": { "type": "boolean" } } } } } }, "FiscalYear": { "type": "object", "properties": { "id": { "type": "integer", "example": 2 }, "company_id": { "type": "integer", "example": 7 }, "code": { "type": "string", "example": "2026" }, "starts_on": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00.000000Z" }, "ends_on": { "type": "string", "format": "date-time", "example": "2026-12-31T00:00:00.000000Z" }, "is_closed": { "type": "boolean", "example": false }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_by": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/Period" } } } }, "FixedAsset": { "type": "object", "properties": { "id": { "type": "integer", "example": 9 }, "company_id": { "type": "integer" }, "source": { "type": "string", "enum": [ "manual", "novadesko" ] }, "external_id": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ], "example": "IMM-2026-003" }, "name": { "type": "string", "example": "Four mixte Rational" }, "category": { "type": "string", "enum": [ "it_equipment", "vehicle", "furniture", "machinery", "building", "software", "other" ] }, "asset_group": { "type": [ "string", "null" ] }, "asset_account_id": { "type": [ "integer", "null" ] }, "depreciation_account_id": { "type": [ "integer", "null" ] }, "expense_account_id": { "type": [ "integer", "null" ] }, "imported_document_id": { "type": [ "integer", "null" ] }, "acquisition_date": { "type": "string", "format": "date-time", "example": "2026-02-01T00:00:00.000000Z" }, "acquisition_cost": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "12400.00" }, "residual_value": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "useful_life_years": { "type": "integer", "example": 5 }, "method": { "type": "string", "enum": [ "linear", "declining" ] }, "prorata_temporis": { "type": "boolean" }, "start_date": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "fully_depreciated", "disposed" ] }, "notes": { "type": [ "string", "null" ] }, "disposed_on": { "type": [ "string", "null" ], "format": "date-time" }, "disposal_price": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$" }, "disposal_entry_id": { "type": [ "integer", "null" ] }, "investment_deduction_pct": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$" }, "investment_deduction_spread": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set while the record is in the recycle bin." }, "deleted_by": { "type": [ "integer", "null" ] }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DepreciationLine" } }, "asset_account": { "type": "object", "properties": { "id": { "type": "integer", "example": 580, "description": "Id" }, "number": { "type": "string", "example": "702000", "description": "Account number" }, "label": { "type": "string", "example": "Prestations de services", "description": "Label" } } }, "depreciation_account": { "type": "object", "properties": { "id": { "type": "integer", "example": 580, "description": "Id" }, "number": { "type": "string", "example": "702000", "description": "Account number" }, "label": { "type": "string", "example": "Prestations de services", "description": "Label" } } }, "expense_account": { "type": "object", "properties": { "id": { "type": "integer", "example": 580, "description": "Id" }, "number": { "type": "string", "example": "702000", "description": "Account number" }, "label": { "type": "string", "example": "Prestations de services", "description": "Label" } } } } }, "ImportedDocument": { "description": "Invoice, credit note or receipt of the company file: synchronised from Novadesko or created by the document importer.", "type": "object", "properties": { "id": { "type": "integer", "example": 87 }, "company_id": { "type": "integer", "example": 7 }, "source": { "type": "string", "example": "novadesko" }, "origin": { "type": [ "string", "null" ], "description": "`novafisko` when created by the importer." }, "external_id": { "type": [ "string", "null" ] }, "type": { "type": "string", "example": "purchases", "description": "purchases, invoices, credit_notes, receipts…" }, "direction": { "type": "string", "enum": [ "sale", "purchase" ] }, "is_credit_note": { "type": "boolean", "example": false }, "nature": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ], "example": "F-2026-0412" }, "payment_provider": { "type": [ "string", "null" ] }, "number_series": { "type": [ "string", "null" ] }, "document_date": { "type": "string", "format": "date-time", "example": "2026-03-15T00:00:00.000000Z" }, "due_date": { "type": [ "string", "null" ], "format": "date-time" }, "subject": { "type": [ "string", "null" ] }, "communication": { "type": [ "string", "null" ] }, "currency": { "type": "string", "example": "EUR" }, "amount_net": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "507.00" }, "amount_vat": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "106.47" }, "amount_gross": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "613.47" }, "is_paid": { "type": "boolean" }, "third_party_id": { "type": [ "integer", "null" ] }, "third_party_name": { "type": [ "string", "null" ], "example": "Brasserie Dubuisson SA" }, "third_party_vat": { "type": [ "string", "null" ] }, "pdf_url": { "type": [ "string", "null" ], "format": "uri" }, "xml_url": { "type": [ "string", "null" ], "format": "uri" }, "status": { "type": "string", "enum": [ "pending", "booked", "ignored" ] }, "journal_entry_id": { "type": [ "integer", "null" ] }, "accountant_locked": { "type": "boolean", "description": "Locked for the shop: only the accountant can change it." }, "novadesko_push_status": { "type": [ "string", "null" ] }, "novadesko_pushed_at": { "type": [ "string", "null" ], "format": "date-time" }, "novadesko_push_error": { "type": [ "string", "null" ] }, "document_import_id": { "type": [ "integer", "null" ] }, "synced_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set while the record is in the recycle bin." }, "deleted_by": { "type": [ "integer", "null" ] }, "third_party": { "type": [ "object", "null" ], "additionalProperties": true }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/ImportedDocumentLine" } }, "journal_entry": { "anyOf": [ { "$ref": "#/components/schemas/JournalEntry" }, { "type": "null" } ] } } }, "ImportedDocumentLine": { "type": "object", "properties": { "id": { "type": "integer", "example": 640 }, "imported_document_id": { "type": "integer", "example": 87 }, "external_id": { "type": [ "string", "null" ] }, "position": { "type": "integer", "example": 1 }, "description": { "type": [ "string", "null" ], "example": "Fûts Bush Caractère 20 L" }, "quantity": { "type": [ "string", "null" ], "example": "6.000" }, "unit_price": { "type": [ "string", "null" ], "example": "84.5000" }, "discount_pct": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$" }, "tax_rate": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$", "example": "21.00" }, "amount_net": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "507.00" }, "amount_vat": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "106.47" }, "recorded_account_number": { "type": [ "string", "null" ], "example": "604000", "description": "Account as encoded at the source (« recorded » layer)." }, "recorded_account_id": { "type": [ "integer", "null" ] }, "actual_account_id": { "type": [ "integer", "null" ], "description": "Account chosen by the accountant (« actual » layer)." }, "vat_code_id": { "type": [ "integer", "null" ] }, "purchase_category": { "type": [ "string", "null" ] }, "corrected_at": { "type": [ "string", "null" ], "format": "date-time" }, "corrected_by": { "type": [ "integer", "null" ] }, "correction_pushed": { "type": "boolean" }, "recorded_account": { "type": [ "object", "null" ], "additionalProperties": true }, "actual_account": { "type": [ "object", "null" ], "additionalProperties": true }, "vat_code": { "type": [ "object", "null" ], "additionalProperties": true } } }, "Integration": { "type": "object", "properties": { "slug": { "type": "string", "example": "novadesko" }, "name": { "type": "string", "example": "Novadesko" }, "category": { "type": "string", "enum": [ "accounting", "banking", "e_invoicing", "documents", "payments", "api" ] }, "description": { "type": "string" }, "logo_url": { "type": [ "string", "null" ], "format": "uri" }, "status": { "type": "string", "enum": [ "available", "beta", "coming_soon" ] }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "import_documents", "import_bank", "import_assets", "export_entries", "e_invoicing" ] } }, "config_schema": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "secret", "select", "bool" ] }, "required": { "type": "boolean" } } } }, "open_tab": { "type": [ "string", "null" ] }, "has_driver": { "type": "boolean" }, "is_enabled": { "type": "boolean" }, "connection": { "type": [ "object", "null" ], "properties": { "is_active": { "type": "boolean" }, "status": { "type": "string", "enum": [ "connected", "disconnected", "error" ] }, "config_masked": { "type": "object", "additionalProperties": true }, "last_sync_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_error": { "type": [ "string", "null" ] } } }, "interested": { "type": "boolean" }, "actions": { "type": "array", "items": { "type": "string", "description": "activate, deactivate, configure, test, sync, open_tab, interest" } } } }, "IntegrationRun": { "type": "object", "properties": { "id": { "type": "integer", "example": 77 }, "status": { "type": "string", "enum": [ "running", "success", "error" ] }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "duration_ms": { "type": [ "integer", "null" ], "example": 1840 }, "summary": { "type": [ "object", "null" ], "additionalProperties": true }, "message": { "type": [ "string", "null" ] } } }, "IntegrationToken": { "description": "Integration token (the secret is only returned once, by the creation).", "type": "object", "properties": { "id": { "type": "integer", "example": 57 }, "name": { "type": "string", "example": "ERP connector" }, "abilities": { "type": "array", "items": { "type": "string", "enum": [ "read", "write", "sync" ] } }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Journal": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 }, "company_id": { "type": "integer", "example": 7 }, "code": { "type": "string", "example": "VEN" }, "label": { "type": "string", "example": "Ventes" }, "type": { "type": "string", "enum": [ "purchase", "sale", "purchase_credit_note", "sale_credit_note", "financial", "miscellaneous" ] }, "control_account_id": { "type": [ "integer", "null" ] }, "iban": { "type": [ "string", "null" ] }, "bic": { "type": [ "string", "null" ] }, "last_number": { "type": "integer", "example": 412 }, "is_active": { "type": "boolean" }, "is_default": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set while the record is in the recycle bin." }, "deleted_by": { "type": [ "integer", "null" ] }, "entries_count": { "type": "integer", "example": 412 }, "control_account": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "example": 580, "description": "Id" }, "number": { "type": "string", "example": "702000", "description": "Account number" }, "label": { "type": "string", "example": "Prestations de services", "description": "Label" } } }, { "type": "null" } ] }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/JournalRule" } } } }, "JournalEntry": { "description": "Posted accounting entry. A posted entry is never modified nor deleted: it is reversed.", "type": "object", "properties": { "id": { "type": "integer", "example": 1284 }, "company_id": { "type": "integer", "example": 7 }, "fiscal_year_id": { "type": "integer", "example": 2 }, "period_id": { "type": "integer", "example": 16 }, "journal_id": { "type": "integer", "example": 3 }, "number": { "type": "integer", "example": 412, "description": "Continuous number in the journal and fiscal year." }, "entry_date": { "type": "string", "format": "date-time", "example": "2026-03-15T00:00:00.000000Z" }, "due_date": { "type": [ "string", "null" ], "format": "date-time" }, "label": { "type": "string", "example": "Facture Brasserie Dubuisson SA" }, "reference": { "type": [ "string", "null" ], "example": "F-2026-0412", "description": "Document number." }, "structured_communication": { "type": [ "string", "null" ], "example": "000000000101", "description": "12 digits, without +++ and /." }, "third_party_id": { "type": [ "integer", "null" ], "example": 18 }, "status": { "type": "string", "enum": [ "posted", "reversed" ] }, "origin": { "type": "string", "example": "manual", "description": "manual, import, bank, recurring, depreciation, vat, year_end…" }, "created_by": { "type": [ "integer", "null" ] }, "posted_at": { "type": "string", "format": "date-time" }, "reversed_entry_id": { "type": [ "integer", "null" ], "description": "Entry this one reverses." }, "reversed_by_entry_id": { "type": [ "integer", "null" ], "description": "Entry that reversed this one." }, "recurring_entry_id": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "journal": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 }, "code": { "type": "string", "example": "VEN" }, "type": { "type": "string", "example": "sale" } } }, "third_party": { "type": "object", "properties": { "id": { "type": "integer", "example": 18 }, "name": { "type": "string", "example": "Brasserie Dubuisson SA" } } }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntryLine" } } } }, "JournalEntryLine": { "type": "object", "properties": { "id": { "type": "integer", "example": 3391 }, "journal_entry_id": { "type": "integer", "example": 1284 }, "position": { "type": "integer", "example": 1 }, "account_id": { "type": "integer", "example": 580 }, "third_party_id": { "type": [ "integer", "null" ] }, "label": { "type": [ "string", "null" ], "example": "Brasserie Dubuisson SA" }, "debit": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "credit": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1000.00" }, "vat_code_id": { "type": [ "integer", "null" ], "example": 4 }, "vat_base": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$", "example": "1000.00" }, "reconciliation_code": { "type": [ "string", "null" ], "example": "AB", "description": "Lettering code." }, "cost_center_id": { "type": [ "integer", "null" ] }, "project_id": { "type": [ "integer", "null" ] }, "reminder_level": { "type": "integer", "example": 0 }, "reminder_sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "account": { "type": "object", "properties": { "id": { "type": "integer", "example": 580, "description": "Id" }, "number": { "type": "string", "example": "702000", "description": "Account number" }, "label": { "type": "string", "example": "Prestations de services", "description": "Label" } } }, "vat_code": { "type": [ "object", "null" ], "additionalProperties": true } } }, "JournalRule": { "description": "Routes imported documents to a journal according to their numbering series, payment provider or third party.", "type": "object", "properties": { "id": { "type": "integer", "example": 4 }, "company_id": { "type": "integer" }, "journal_id": { "type": "integer", "example": 3 }, "direction": { "type": "string", "enum": [ "sale", "purchase" ] }, "match_field": { "type": "string", "enum": [ "payment_provider", "number_series", "number_prefix", "third_party" ] }, "match_value": { "type": "string", "example": "TK" }, "priority": { "type": "integer", "example": 100 }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set while the record is in the recycle bin." }, "deleted_by": { "type": [ "integer", "null" ] }, "journal": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 }, "code": { "type": "string", "example": "VEN" }, "label": { "type": "string", "example": "Ventes" }, "type": { "type": "string", "example": "sale" } } } } }, "Licence": { "description": "Licence and subscription of the firm: plan, status, usage of the month, estimate, last statements.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "none", "trial", "active", "past_due", "suspended", "cancelled" ] }, "subscription": { "type": [ "object", "null" ], "additionalProperties": true }, "plan": { "type": [ "object", "null" ], "additionalProperties": true }, "usage": { "type": "object", "properties": { "month": { "type": "string", "example": "2026-10" }, "companies": { "type": "integer", "example": 25 }, "users": { "type": "integer", "example": 4 }, "bank_accounts": { "type": "integer", "example": 31 }, "rows": { "type": "array", "items": { "type": "object", "properties": { "company_id": { "type": "integer" }, "token": { "type": "string", "minLength": 12, "maxLength": 12 }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "bank_accounts": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "active" }, "activated_at": { "type": "string", "format": "date-time" }, "deactivated_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "max_companies": { "type": [ "integer", "null" ] }, "over_limit": { "type": "boolean", "example": false }, "suggestion": { "type": [ "string", "null" ] } } }, "estimate": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Estimated invoice of the month (excl. VAT)." }, "companies_detail": { "type": "array", "items": { "type": "object", "properties": { "company_id": { "type": "integer" }, "name": { "type": "string" }, "public_token": { "type": "string", "minLength": 12, "maxLength": 12 }, "status": { "type": "string", "example": "active" }, "activated_at": { "type": "string", "format": "date-time" }, "deactivated_at": { "type": [ "string", "null" ], "format": "date-time" }, "billable": { "type": "boolean" } } } }, "next_month_preview": { "type": "object", "properties": { "companies": { "type": "integer", "example": 25 }, "total": { "type": "number", "example": 121.5 } } }, "over_limit": { "type": "boolean", "example": false }, "over_limit_firm_total": { "type": [ "number", "null" ] }, "entitlements": { "type": "object", "properties": { "accounting": { "type": "boolean" }, "peppol": { "type": "boolean" }, "coda": { "type": "boolean" }, "client_portal": { "type": "boolean" }, "client_invoicing": { "type": "boolean" }, "document_import": { "type": "boolean" } } }, "limits": { "type": "object", "properties": { "max_users": { "type": [ "integer", "null" ] }, "max_companies": { "type": [ "integer", "null" ] }, "users_count": { "type": "integer", "example": 4 }, "companies_count": { "type": "integer", "example": 25 } } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "warning": { "type": [ "string", "null" ] }, "activation": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Active licence key (masked) when the subscription comes from a key." }, "statements": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "options_available": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "client_portal", "client_invoicing" ] }, "name": { "type": "string", "example": "Portail client" }, "price_monthly": { "type": "number", "example": 6.9 }, "unit": { "type": "string", "example": "client" } } } }, "can_manage": { "type": "boolean" } } }, "MailLog": { "type": "object", "properties": { "id": { "type": "integer", "example": 9012 }, "template_key": { "type": "string", "example": "documents.send" }, "to": { "type": "string", "format": "email", "example": "gerant@comptoir-montois.example" }, "subject": { "type": "string", "example": "Vos documents comptables" }, "status": { "type": "string", "enum": [ "queued", "sent", "failed", "bounced" ] }, "locale": { "type": "string", "example": "fr" }, "created_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "opened_at": { "type": [ "string", "null" ], "format": "date-time" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "balance-2026.pdf" }, "size": { "type": "integer", "example": 48211 } } } } } }, "Message": { "type": "object", "properties": { "message": { "type": "string", "example": "Mot de passe modifié.", "description": "Translated confirmation." } } }, "Pagination": { "description": "Laravel length-aware pagination envelope; `data` holds the items.", "type": "object", "properties": { "current_page": { "type": "integer", "example": 1 }, "data": { "type": "array", "items": [] }, "first_page_url": { "type": [ "string", "null" ], "format": "uri" }, "from": { "type": [ "integer", "null" ], "example": 1 }, "last_page": { "type": "integer", "example": 4 }, "last_page_url": { "type": [ "string", "null" ], "format": "uri" }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "format": "uri" }, "label": { "type": "string", "example": "1" }, "page": { "type": [ "integer", "null" ] }, "active": { "type": "boolean" } } } }, "next_page_url": { "type": [ "string", "null" ], "format": "uri" }, "path": { "type": "string", "format": "uri" }, "per_page": { "type": "integer", "example": 50 }, "prev_page_url": { "type": [ "string", "null" ], "format": "uri" }, "to": { "type": [ "integer", "null" ], "example": 50 }, "total": { "type": "integer", "example": 187 } } }, "PeppolAccessPoint": { "type": "object", "properties": { "smp_host": { "type": [ "string", "null" ], "example": "smp.b2brouter.net" }, "provider_name": { "type": [ "string", "null" ], "example": "B2Brouter" }, "endpoint_url": { "type": [ "string", "null" ], "format": "uri" }, "technical_contact": { "type": [ "string", "null" ] } } }, "PeppolDocumentType": { "type": "object", "properties": { "id": { "type": "string", "example": "bis_billing_invoice" }, "name": { "type": "string", "example": "Invoice BIS Billing 3.0" }, "family": { "type": "string", "example": "billing" }, "description": { "type": "string", "example": "Facture électronique européenne (EN 16931), format Peppol BIS Billing 3.0." }, "document_id": { "type": "string", "description": "Full Peppol document type identifier." } } }, "PeppolState": { "description": "Peppol registration state of a company file.", "type": "object", "properties": { "identity": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Raw registration record." }, "participant_id": { "type": [ "string", "null" ], "example": "0208:0477472701" }, "status": { "type": "string", "enum": [ "none", "pending", "active", "inactive", "deleted", "error", "external" ] }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" } } }, "transport": { "type": [ "object", "null" ], "description": "Transport options: enabled, reception, standard_documents, invoice, credit_note, self_billing, order, application_response.", "additionalProperties": { "type": "boolean" } }, "smp": { "type": "object", "properties": { "published": { "type": "boolean" }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "access_point": { "$ref": "#/components/schemas/PeppolAccessPoint" }, "supported_documents": { "type": "array", "items": { "$ref": "#/components/schemas/PeppolDocumentType" } }, "can_register": { "type": "boolean" }, "blockers": { "type": "array", "items": { "type": "string", "description": "Translated reason." } }, "blocker_codes": { "type": "array", "items": { "type": "string", "description": "Machine reason (missing_vat_number, missing_address…)." } }, "managed_by_novadesko": { "type": "boolean" }, "registered_elsewhere": { "type": "boolean", "description": "The participant is already published by another access point." }, "external_provider": { "type": [ "string", "null" ] }, "provider_configured": { "type": "boolean" }, "environment": { "type": "string", "enum": [ "production", "staging" ] }, "contact": { "type": "object", "additionalProperties": true }, "last_error": { "type": [ "string", "null" ] } } }, "PeppolThirdPartyStatus": { "type": "object", "properties": { "identifier": { "type": [ "string", "null" ], "example": "0208:0402531376" }, "registered": { "type": [ "boolean", "null" ] }, "access_point": { "anyOf": [ { "$ref": "#/components/schemas/PeppolAccessPoint" }, { "type": "null" } ] }, "document_types": { "type": "array", "items": { "$ref": "#/components/schemas/PeppolDocumentType" } }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "stale": { "type": "boolean" }, "error": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ], "example": "sml+smp" } } }, "Period": { "type": "object", "properties": { "id": { "type": "integer", "example": 16 }, "fiscal_year_id": { "type": "integer", "example": 2 }, "number": { "type": "integer", "example": 3, "description": "0 = opening, 1-12 = months, 99 = closing." }, "label": { "type": "string", "example": "Mars 2026" }, "starts_on": { "type": "string", "format": "date-time" }, "ends_on": { "type": "string", "format": "date-time" }, "is_locked": { "type": "boolean", "example": false }, "locked_at": { "type": [ "string", "null" ], "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." } } }, "PeriodLockedError": { "description": "422 of a write whose period is locked or whose fiscal year is closed.", "type": "object", "properties": { "message": { "type": "string", "example": "La période Mars 2026 est verrouillée." }, "code": { "type": "string", "enum": [ "period_locked" ] }, "reason": { "type": "string", "enum": [ "period_locked", "fiscal_year_closed" ] }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "entry_date": [ "La période Mars 2026 est verrouillée." ] } } }, "required": [ "message", "code", "reason", "errors" ] }, "PricingGrid": { "type": "object", "properties": { "currency": { "type": "string", "example": "EUR" }, "vat_included": { "type": "boolean", "example": false }, "plans": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "starter", "firm" ] }, "name": { "type": "string", "example": "Firm" }, "kind": { "type": "string", "enum": [ "starter", "firm" ] }, "base_price_monthly": { "type": "number", "example": 49 }, "per_company": { "type": "number", "example": 2.9 }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "up_to": { "type": [ "integer", "null" ], "example": 100 }, "price": { "type": "number", "example": 2.9 } } } }, "max_companies": { "type": [ "integer", "null" ] }, "peppol_fair_use_per_company": { "type": "integer", "example": 100 }, "annual_discount_pct": { "type": "number", "example": 10 }, "included": { "type": "array", "items": { "type": "string", "example": "Unlimited users", "description": "Feature label" } } } } }, "options": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "client_portal" }, "name": { "type": "string", "example": "Client portal" }, "price_monthly": { "type": "number", "example": 6.9 }, "unit": { "type": "string", "example": "client" } } } }, "annual_discount_pct": { "type": "number", "example": 10 }, "winauditor": { "type": "object", "additionalProperties": true, "description": "Reference prices used for the comparison." }, "pilot": { "type": "object", "properties": { "free_months": { "type": "integer", "example": 3 }, "max_firms": { "type": "integer", "example": 20 } } } } }, "PricingSimulation": { "type": "object", "properties": { "companies": { "type": "integer", "example": 25 }, "yearly": { "type": "boolean", "example": false }, "starter": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Null when the plan cannot hold that many companies." }, "firm": { "type": "object", "properties": { "plan": { "type": "string", "example": "firm" }, "billing_interval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "companies": { "type": "integer", "example": 25 }, "base": { "type": "number", "example": 49 }, "companies_breakdown": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 100 }, "quantity": { "type": "integer", "example": 25 }, "unit_price": { "type": "number", "example": 2.9 }, "total": { "type": "number", "example": 72.5 } } } }, "companies_total": { "type": "number", "example": 72.5 }, "options": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "options_total": { "type": "number", "example": 0 }, "pilot_discount": { "type": "number", "example": 0 }, "annual_discount_pct": { "type": "number", "example": 0 }, "annual_discount": { "type": "number", "example": 0 }, "discount": { "type": "number", "example": 0 }, "total": { "type": "number", "example": 121.5 }, "yearly_total": { "type": "number", "example": 1458 }, "name": { "type": "string", "example": "Firm" }, "saving_vs_winauditor": { "type": "number", "example": 36 }, "saving_pct": { "type": "number", "example": 22.9 } } }, "winauditor": { "type": "number", "example": 157.5 }, "cheapest": { "type": "string", "enum": [ "starter", "firm" ] } } }, "RecurringEntry": { "type": "object", "properties": { "id": { "type": "integer", "example": 5 }, "company_id": { "type": "integer" }, "journal_id": { "type": "integer", "example": 5 }, "label": { "type": "string", "example": "Loyer mensuel" }, "reference": { "type": [ "string", "null" ] }, "third_party_id": { "type": [ "integer", "null" ] }, "frequency": { "type": "string", "enum": [ "monthly", "quarterly", "yearly" ] }, "next_date": { "type": "string", "format": "date-time", "example": "2026-04-01T00:00:00.000000Z" }, "end_date": { "type": [ "string", "null" ], "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "integer", "example": 368 }, "debit": { "type": [ "string", "null" ], "example": "1500.00" }, "credit": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "third_party_id": { "type": [ "integer", "null" ] } } } }, "is_active": { "type": "boolean" }, "last_generated_on": { "type": [ "string", "null" ], "format": "date" }, "generated_count": { "type": "integer", "example": 3 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set while the record is in the recycle bin." }, "deleted_by": { "type": [ "integer", "null" ] }, "journal": { "type": "object", "properties": { "id": { "type": "integer" }, "code": { "type": "string", "example": "OD" }, "label": { "type": "string", "example": "Opérations diverses" } } }, "third_party": { "type": [ "object", "null" ], "additionalProperties": true } } }, "Revision": { "description": "One line of the version history.", "type": "object", "properties": { "id": { "type": "integer", "example": 2301 }, "action": { "type": "string", "enum": [ "created", "updated", "deleted", "restored", "reverted", "synced" ] }, "effect": { "type": "string", "example": "updated" }, "action_label": { "type": "string", "example": "Modification · Tiers" }, "subject_type": { "type": "string", "example": "third_parties" }, "subject_type_label": { "type": "string", "example": "Tiers" }, "subject_id": { "type": "integer", "example": 18 }, "subject_label": { "type": "string", "example": "DUBUISSON · Brasserie Dubuisson SA" }, "user": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "example": 12, "description": "User id" }, "name": { "type": "string", "example": "Claire Dumont", "description": "Name" } } }, { "type": "null" } ] }, "actor_name": { "type": [ "string", "null" ], "example": "Claire Dumont" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "example": "payment_terms_days" }, "label": { "type": "string", "example": "Délai de paiement" }, "old": [], "new": [] } } }, "version": { "type": "integer", "example": 4 }, "operation_id": { "type": "string", "format": "uuid" }, "client_mutation_id": { "type": [ "string", "null" ] }, "origin": { "type": "string", "enum": [ "online", "offline_sync", "system", "bridge" ] }, "device_id": { "type": [ "string", "null" ] }, "device_name": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "reverts_revision_id": { "type": [ "integer", "null" ] }, "reverted_at": { "type": [ "string", "null" ], "format": "date-time" }, "reverted_by_revision_id": { "type": [ "integer", "null" ] }, "occurred_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "can_revert": { "type": "boolean" }, "revert_blocked_reason": { "type": [ "string", "null" ] }, "revert_blocked_message": { "type": [ "string", "null" ] }, "revert_effect": { "type": [ "string", "null" ], "description": "update, trash, restore, recreate or reverse." }, "snapshot_before": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Single revision only." }, "snapshot_after": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Single revision only." }, "ip": { "type": [ "string", "null" ], "description": "Single revision only." } } }, "SheetView": { "type": "object", "properties": { "sheet": { "anyOf": [ { "$ref": "#/components/schemas/CompanySheet" }, { "type": "null" } ] }, "sheet_at": { "type": [ "string", "null" ], "format": "date-time" }, "address": { "type": "object", "properties": { "street": { "type": [ "string", "null" ], "example": "Grand-Place", "description": "Street" }, "house_number": { "type": [ "string", "null" ], "example": "14", "description": "Number" }, "box": { "type": [ "string", "null" ], "description": "Box" }, "postal_code": { "type": [ "string", "null" ], "example": "7000", "description": "Postal code" }, "city": { "type": [ "string", "null" ], "example": "Mons", "description": "City" }, "country": { "type": [ "string", "null" ], "example": "BE", "description": "ISO 3166-1 alpha-2" } } }, "address_line": { "type": [ "string", "null" ] }, "legal_form": { "type": [ "object", "null" ], "additionalProperties": true }, "nace_codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "classification": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "is_main": { "type": "boolean" } } } }, "main_nace_code": { "type": [ "string", "null" ] }, "vat_number_formatted": { "type": [ "string", "null" ], "example": "BE 0477.472.701" }, "map": { "type": "object", "properties": { "query": { "type": "string", "example": "Grand-Place 14, 7000 Mons, Belgique", "description": "Address used for the map" }, "apple_url": { "type": "string", "format": "uri" }, "google_url": { "type": "string", "format": "uri" }, "static_url": { "type": [ "string", "null" ], "format": "uri" }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] } } } } }, "SyncChange": { "type": "object", "properties": { "resource": { "type": "string", "example": "third_parties" }, "op": { "type": "string", "enum": [ "upsert", "delete" ] }, "id": { "type": "integer", "example": 18 }, "version": { "type": [ "integer", "null" ], "example": 4 }, "data": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Resource serialised as by its list endpoint; null for a tombstone." }, "changed_at": { "type": "string", "format": "date-time" }, "seq": { "type": "integer", "example": 1042, "description": "Position in the change feed." } } }, "SyncConflict": { "type": "object", "properties": { "id": { "type": "integer", "example": 8 }, "status": { "type": "string", "enum": [ "open", "resolved" ] }, "type": { "type": "string", "enum": [ "field", "delete_vs_update", "update_vs_delete", "duplicate", "locked" ] }, "type_label": { "type": "string" }, "resource": { "type": "string", "example": "third_parties" }, "record_id": { "type": [ "integer", "null" ] }, "subject_id": { "type": [ "integer", "null" ] }, "subject_label": { "type": [ "string", "null" ] }, "client_mutation_id": { "type": [ "string", "null" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "server": [], "client": [], "winner": { "type": "string" }, "rule": { "type": "string" } } } }, "client_data": { "type": [ "object", "null" ], "additionalProperties": true }, "server_data": { "type": [ "object", "null" ], "additionalProperties": true }, "server_version": { "type": [ "integer", "null" ] }, "winner": { "type": [ "string", "null" ] }, "loser": { "type": [ "string", "null" ] }, "resolution": { "type": [ "string", "null" ] }, "resolved_by": { "type": [ "integer", "null" ] }, "client_user": { "type": [ "object", "null" ], "additionalProperties": true }, "server_user": { "type": [ "object", "null" ], "additionalProperties": true }, "resolved_by_user": { "type": [ "object", "null" ], "additionalProperties": true }, "device_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "choices": { "type": "array", "items": { "type": "string", "enum": [ "server", "client", "merge" ] } } } }, "SyncMutation": { "description": "One action made offline, replayed through the matching REST action (same validation, same body).", "type": "object", "properties": { "client_mutation_id": { "type": "string", "format": "uuid", "description": "Idempotence key." }, "occurred_at": { "type": "string", "format": "date-time", "description": "Date of the action on the device." }, "operation_id": { "type": "string", "format": "uuid" }, "resource": { "type": "string", "example": "third_parties", "description": "third_parties, accounts, journals, journal_rules, bank_rules, recurring_entries, analytic_codes, fixed_assets, entries, documents, document_lines, bank_transactions, company_settings." }, "op": { "type": "string", "enum": [ "create", "update", "delete", "action" ] }, "action": { "type": "string", "enum": [ "ignore", "restore", "entry", "invoice", "reverse", "book", "update_line" ] }, "id": { "type": [ "integer", "string", "null" ], "description": "Server id, or the `tmp-…` id of a record created earlier in the queue." }, "client_temp_id": { "type": "string", "example": "tmp-3c1f", "description": "Temporary id of a creation (`tmp-`), mapped to the server id." }, "parent_id": { "type": [ "integer", "string", "null" ] }, "base_version": { "type": "integer", "description": "Version the client edited." }, "data": { "type": "object", "additionalProperties": true, "description": "Body of the equivalent REST request." } }, "required": [ "client_mutation_id", "resource", "op" ] }, "SyncMutationResult": { "type": "object", "properties": { "client_mutation_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "applied", "duplicate", "conflict", "rejected" ] }, "original_status": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "locked, not_supported_offline, validation, not_found, forbidden, invalid_mutation, unknown_temp_id, unprocessable, server_error." }, "message": { "type": [ "string", "null" ] }, "resource": { "type": "string" }, "op": { "type": "string" }, "action": { "type": [ "string", "null" ] }, "id": { "type": [ "integer", "null" ] }, "client_temp_id": { "type": [ "string", "null" ] }, "version": { "type": [ "integer", "null" ] }, "data": { "type": [ "object", "null" ], "additionalProperties": true }, "errors": { "type": [ "object", "null" ], "additionalProperties": true }, "conflict": { "type": [ "object", "null" ], "properties": { "server_version": { "type": "integer" }, "server_data": { "type": "object" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "client": [], "server": [], "winner": { "type": "string", "enum": [ "client", "server" ] }, "rule": { "type": "string" } } } }, "resolution": { "type": "string" } } }, "duplicate_of": { "type": [ "integer", "null" ] }, "retryable": { "type": "boolean" } } }, "ThirdParty": { "description": "Customer or supplier of a company file.", "type": "object", "properties": { "id": { "type": "integer", "example": 18 }, "company_id": { "type": "integer", "example": 7 }, "type": { "type": "string", "enum": [ "customer", "supplier" ] }, "code": { "type": "string", "example": "DUBUISSON" }, "name": { "type": "string", "example": "Brasserie Dubuisson SA" }, "contact_name": { "type": [ "string", "null" ] }, "vat_number": { "type": [ "string", "null" ], "example": "BE0402531376" }, "enterprise_number": { "type": [ "string", "null" ], "example": "0402531376" }, "legal_form_code": { "type": [ "string", "null" ] }, "vat_status": { "type": "string", "enum": [ "subject", "not_subject", "exempt", "intra_eu", "non_eu" ] }, "country": { "type": "string", "example": "BE" }, "language": { "type": [ "string", "null" ], "example": "fr" }, "category": { "type": [ "string", "null" ] }, "currency": { "type": "string", "example": "EUR" }, "address": { "type": [ "string", "null" ], "example": "Chaussée de Mons 28" }, "house_number": { "type": [ "string", "null" ] }, "box": { "type": [ "string", "null" ] }, "address_line_2": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ], "example": "7904" }, "city": { "type": [ "string", "null" ], "example": "Pipaix" }, "nace_code": { "type": [ "string", "null" ] }, "iban": { "type": [ "string", "null" ], "example": "BE71096123456769" }, "bic": { "type": [ "string", "null" ], "example": "GKCCBEBB" }, "bank_account": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email", "example": "compta@dubuisson.example" }, "phone": { "type": [ "string", "null" ] }, "fax": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "payment_terms_days": { "type": "integer", "example": 30 }, "form_281_50_type": { "type": [ "string", "null" ] }, "profession_281_50": { "type": [ "string", "null" ] }, "is_natural_person": { "type": "boolean", "example": false }, "notes": { "type": [ "string", "null" ] }, "default_vat_code_id": { "type": [ "integer", "null" ] }, "default_account_id": { "type": [ "integer", "null" ] }, "vies_valid": { "type": [ "boolean", "null" ] }, "vies_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "vies_name": { "type": [ "string", "null" ] }, "peppol_identifier": { "type": [ "string", "null" ], "example": "0208:0402531376" }, "peppol_registered": { "type": [ "boolean", "null" ] }, "peppol_access_point": { "type": [ "object", "null" ], "additionalProperties": true }, "peppol_document_types": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PeppolDocumentType" } }, "peppol_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set while the record is in the recycle bin." }, "deleted_by": { "type": [ "integer", "null" ] }, "default_account": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Loaded on the single sheet." }, "default_vat_code": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Loaded on the single sheet." } } }, "TrashItem": { "type": "object", "properties": { "type": { "type": "string", "example": "third_parties" }, "id": { "type": "integer", "example": 18 }, "label": { "type": "string", "example": "DUBUISSON · Brasserie Dubuisson SA" }, "deleted_at": { "type": "string", "format": "date-time" }, "deleted_by": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "example": 12, "description": "User id" }, "name": { "type": "string", "example": "Claire Dumont", "description": "Name" } } }, { "type": "null" } ] }, "purge_at": { "type": "string", "format": "date-time", "description": "Date of the definitive purge." }, "restorable": { "type": "boolean" }, "blocked_reason": { "type": [ "string", "null" ] }, "blocked_message": { "type": [ "string", "null" ] }, "version": { "type": "integer" } } }, "Treasury": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "journal_id": { "type": "integer", "example": 7 }, "code": { "type": "string", "example": "BNP" }, "label": { "type": "string", "example": "BNP Paribas Fortis" }, "iban": { "type": [ "string", "null" ] }, "account": { "type": "string", "example": "550000" }, "accounting_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "19630.11" }, "last_statement_balance": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$", "example": "19630.11" }, "last_statement_date": { "type": [ "string", "null" ], "format": "date" }, "pending_count": { "type": "integer", "example": 3 }, "pending_amount": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "1842.50" }, "difference": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" } } } }, "total_accounting_balance": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "21480.61" } } }, "User": { "description": "Authenticated user with the firms it belongs to.", "type": "object", "properties": { "id": { "type": "integer", "example": 12 }, "name": { "type": "string", "example": "Claire Dumont" }, "email": { "type": "string", "format": "email" }, "locale": { "type": "string", "enum": [ "fr", "nl", "en", "de" ] }, "email_verified": { "type": "boolean" }, "pending_email": { "type": [ "string", "null" ], "format": "email", "description": "New address waiting for confirmation." }, "is_platform_admin": { "type": "boolean", "example": false }, "is_demo": { "type": "boolean", "example": false, "description": "True for the ephemeral user of the demo firm." }, "firms": { "type": "array", "items": { "type": "object", "properties": { "public_token": { "type": "string", "minLength": 12, "maxLength": 12, "example": "NDTQVQU4AUAV" }, "name": { "type": "string", "example": "Fiduciaire Dumont & Associés" }, "role": { "type": "string", "enum": [ "admin", "manager", "encoder", "reviewer" ] } } } }, "managed_firms": { "type": "array", "items": { "type": "object", "properties": { "public_token": { "type": "string", "minLength": 12, "maxLength": 12, "example": "NDTQVQU4AUAV" }, "name": { "type": "string", "example": "Fiduciaire Dumont & Associés" } } } } } }, "VatCode": { "type": "object", "properties": { "id": { "type": "integer", "example": 4 }, "company_id": { "type": "integer" }, "code": { "type": "string", "example": "V21" }, "label": { "type": "string", "example": "Ventes 21 %" }, "direction": { "type": "string", "enum": [ "sale", "purchase" ] }, "rate": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "21.00" }, "nature": { "type": "string", "enum": [ "standard", "intra_eu", "cocontractor", "export", "exempt", "import", "out_of_scope" ] }, "deductible_pct": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "100.00" }, "base_grid": { "type": [ "string", "null" ], "example": "03", "description": "Grid of the taxable base." }, "vat_grid": { "type": [ "string", "null" ], "example": "54", "description": "Grid of the VAT." }, "due_vat_grid": { "type": [ "string", "null" ], "description": "Grid of the VAT due (reverse charge)." }, "credit_base_grid": { "type": [ "string", "null" ], "example": "49", "description": "Grid of the base on a credit note." }, "credit_vat_grid": { "type": [ "string", "null" ], "example": "64" }, "vat_account": { "type": [ "string", "null" ], "example": "451100" }, "due_vat_account": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "sort_order": { "type": "integer", "example": 13 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." } } }, "VatComputation": { "type": "object", "properties": { "grids": { "type": "object", "description": "Belgian VAT grids: grid number => amount (decimal string).", "additionalProperties": { "type": "string" }, "example": { "00": "0.00", "01": "0.00", "02": "0.00", "03": "1000.00", "54": "210.00", "59": "52.50", "71": "157.50", "72": "0.00", "81": "0.00", "82": "250.00", "83": "0.00" } }, "amount_due": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "157.50", "description": "Grid 71." }, "amount_refund": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00", "description": "Grid 72." }, "warnings": { "type": "array", "items": { "type": "string" } }, "entries": { "type": "integer", "example": 38, "description": "Entries carrying VAT in the period." } } }, "VatDeclaration": { "type": "object", "properties": { "id": { "type": "integer", "example": 14 }, "company_id": { "type": "integer" }, "period_type": { "type": "string", "enum": [ "monthly", "quarterly" ] }, "year": { "type": "integer", "example": 2026 }, "period": { "type": "integer", "example": 1, "description": "Month (1-12) or quarter (1-4)." }, "starts_on": { "type": "string", "format": "date-time" }, "ends_on": { "type": "string", "format": "date-time" }, "grids": { "type": "object", "description": "Belgian VAT grids: grid number => amount (decimal string).", "additionalProperties": { "type": "string" }, "example": { "00": "0.00", "01": "0.00", "02": "0.00", "03": "1000.00", "54": "210.00", "59": "52.50", "71": "157.50", "72": "0.00", "81": "0.00", "82": "250.00", "83": "0.00" } }, "amount_due": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "157.50" }, "amount_refund": { "type": "string", "pattern": "^-?\\d+\\.\\d{2}$", "example": "0.00" }, "status": { "type": "string", "enum": [ "draft", "validated", "submitted" ] }, "validated_at": { "type": [ "string", "null" ], "format": "date-time" }, "validated_by": { "type": [ "integer", "null" ] }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time" }, "submission_reference": { "type": [ "string", "null" ], "description": "Intervat receipt reference." }, "journal_entry_id": { "type": [ "integer", "null" ], "description": "VAT settlement entry." }, "warnings": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "lock_version": { "type": "integer", "example": 3, "description": "Internal lock counter." }, "version": { "type": "integer", "example": 3, "description": "Version of the record, to send back as `X-Base-Version` / `base_version`." }, "journal_entry": { "type": [ "object", "null" ], "additionalProperties": true } } }, "VersionConflict": { "description": "409 of the optimistic lock (`X-Base-Version`).", "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "conflict" ] }, "server_version": { "type": "integer", "example": 4, "description": "Current version on the server." }, "server_data": { "type": "object", "additionalProperties": true, "description": "Current state of the record." } }, "required": [ "message", "code", "server_version", "server_data" ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "integer", "example": 1871 }, "event_id": { "type": "string", "example": "evt_01JD8X5Q2M7Z4W9K3T6B0N1VCE" }, "event": { "type": "string", "example": "entry.posted" }, "status": { "type": "string", "enum": [ "pending", "delivered", "failed" ] }, "attempts": { "type": "integer", "example": 1, "description": "8 attempts at most." }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "response_status": { "type": [ "integer", "null" ], "example": 200 }, "response_excerpt": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ], "example": 184 }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "payload": { "$ref": "#/components/schemas/WebhookEvent" }, "attempt": { "type": "integer", "example": 1, "description": "Alias of `attempts`." }, "http_status": { "type": [ "integer", "null" ], "example": 200, "description": "Alias of `response_status`." } } }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 }, "url": { "type": "string", "format": "uri", "example": "https://erp.example.com/hooks/novafisko" }, "description": { "type": [ "string", "null" ], "example": "ERP connector" }, "events": { "type": "array", "items": { "type": "string", "example": "entry.posted", "description": "Event name, or `*` for all." } }, "is_active": { "type": "boolean" }, "secret_hint": { "type": "string", "example": "whsec_…ab12", "description": "Masked signing secret." }, "last_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_status": { "type": [ "string", "null" ], "example": "delivered", "description": "Status of the last delivery." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WebhookEvent": { "description": "Body POSTed to a webhook endpoint. Verify `X-Novafisko-Signature` before trusting it.", "type": "object", "properties": { "id": { "type": "string", "example": "evt_01JD8X5Q2M7Z4W9K3T6B0N1VCE", "description": "Unique event id; use it to deduplicate." }, "event": { "type": "string", "example": "entry.posted" }, "api_version": { "type": "string", "example": "v1" }, "created_at": { "type": "string", "format": "date-time", "description": "UTC." }, "firm": { "type": "object", "properties": { "public_token": { "type": "string", "minLength": 12, "maxLength": 12, "example": "NDTQVQU4AUAV" }, "name": { "type": "string", "example": "Fiduciaire Dumont & Associés" } } }, "company": { "type": [ "object", "null" ], "properties": { "public_token": { "type": "string", "example": "XBVD5O1L29HC" }, "name": { "type": "string", "example": "Le Comptoir Montois SRL" } } }, "data": { "type": "object", "additionalProperties": true, "description": "Event-specific payload (ids, references, amounts)." } }, "required": [ "id", "event", "api_version", "created_at", "firm", "data" ] } } } }