{ "openapi": "3.1.0", "info": { "title": "Terramine own-deployment CRM and ERP integration", "version": "1.0.0", "description": "Own deployment only: customer integration operations mounted by the operational Desk. Hosted workspaces use the separate contract at https://docs.terraminedesk.ai/docs/openapi.json. Send one Authorization: Bearer tdk_... header or one X-API-Key header; do not combine them. Keys are created by an administrator in Admin > Connections > Desk open API. Each operation requires its stated key scope. Module availability and the installed database schema still apply. Internal dashboard administration routes are outside this contract. Response records may include additional deployment-specific fields." }, "x-deployment": "own", "servers": [ { "url": "/", "description": "Your own Desk origin" } ], "security": [ { "BearerKey": [] }, { "ApiKey": [] } ], "tags": [ { "name": "Customers" }, { "name": "Suppliers" }, { "name": "Parts and stock" }, { "name": "Customer orders" }, { "name": "Sales documents" }, { "name": "Purchase orders" }, { "name": "Payments" }, { "name": "Accounting" }, { "name": "CRM deals" } ], "paths": { "/api/v1/customers": { "get": { "operationId": "listCustomers", "tags": [ "Customers" ], "summary": "Customers, oldest change first.", "x-deployment": "own", "x-required-scope": "customers:read", "parameters": [ { "name": "updated_since", "in": "query", "schema": { "type": "string", "default": "" }, "description": "ISO 8601 date-time or Unix seconds; omitted means all history. For customers/orders only, opaque cursors are accepted when stable_cursor=true." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Results are clamped to 1\u2013200. A value of 0 uses the default of 50; invalid integer syntax returns 422." }, { "name": "q", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Search text." }, { "name": "stable_cursor", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Own deployment defaults to false (timestamp-only pagination). Opt in to timestamp/id pagination; keep true when reusing the opaque next_updated_since cursor, and retain the same filters. Timestamp-only pagination can skip records sharing a page-boundary timestamp." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_updated_since" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "next_updated_since": { "type": [ "number", "string", "null" ], "description": "Null when there is no further page. A Unix timestamp by default; customers/orders return an opaque string when stable_cursor=true." } } } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "operationId": "createCustomer", "tags": [ "Customers" ], "summary": "Create a customer.", "x-deployment": "own", "x-required-scope": "customers:write", "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": {}, "name": {} }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" }, "address1": { "type": "string" }, "postal": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "website": { "type": "string" }, "tax_no": { "type": "string" } } } } } }, "description": "Create a customer; a nonblank name is required. Unknown fields are ignored." } }, "/api/v1/suppliers": { "get": { "operationId": "listSuppliers", "tags": [ "Suppliers" ], "summary": "Suppliers by name.", "x-deployment": "own", "x-required-scope": "suppliers:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Results are clamped to 1\u2013200. A value of 0 uses the default of 50; invalid integer syntax returns 422." }, { "name": "q", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Search text." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_updated_since" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": {}, "name": {}, "country": {}, "city": {}, "currency": {}, "email": {}, "phone": {}, "website": {}, "tax_no": {} }, "additionalProperties": true } }, "next_updated_since": { "type": "null", "description": "This search is capped by limit and has no continuation cursor." } } } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/parts": { "get": { "operationId": "listParts", "tags": [ "Parts and stock" ], "summary": "Parts with the quantity on hand.", "x-deployment": "own", "x-required-scope": "parts:read", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Search text." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Results are clamped to 1\u2013200. A value of 0 uses the default of 50; invalid integer syntax returns 422." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_updated_since" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": {}, "pn": {}, "brand": {}, "description": {}, "uom": {}, "weight": {}, "hs_code": {}, "origin": {}, "on_hand": {} }, "additionalProperties": true } }, "next_updated_since": { "type": "null", "description": "This search is capped by limit and has no continuation cursor." } } } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/orders": { "get": { "operationId": "listOrders", "tags": [ "Customer orders" ], "summary": "Customer orders, oldest change first.", "x-deployment": "own", "x-required-scope": "orders:read", "parameters": [ { "name": "updated_since", "in": "query", "schema": { "type": "string", "default": "" }, "description": "ISO 8601 date-time or Unix seconds; omitted means all history. For customers/orders only, opaque cursors are accepted when stable_cursor=true." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Results are clamped to 1\u2013200. A value of 0 uses the default of 50; invalid integer syntax returns 422." }, { "name": "status", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Exact order status filter." }, { "name": "stable_cursor", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Own deployment defaults to false (timestamp-only pagination). Opt in to timestamp/id pagination; keep true when reusing the opaque next_updated_since cursor, and retain the same filters. Timestamp-only pagination can skip records sharing a page-boundary timestamp." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_updated_since" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderSummary" } }, "next_updated_since": { "type": [ "number", "string", "null" ], "description": "Null when there is no further page. A Unix timestamp by default; customers/orders return an opaque string when stable_cursor=true." } } } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "operationId": "createDraftOrder", "tags": [ "Customer orders" ], "summary": "A customer's request: a draft order a person prices.", "x-deployment": "own", "x-required-scope": "orders:write", "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_id", "lines" ], "properties": { "customer_id": { "type": "string" }, "lines": { "type": "array", "minItems": 1, "maxItems": 300, "items": { "type": "object", "properties": { "pn": { "type": "string" }, "qty": { "type": "number" }, "description": { "type": "string" }, "brand": { "type": "string" } } } }, "currency": { "type": "string" }, "client_ref": { "type": "string" }, "note": { "type": "string" }, "external_ref": { "type": "string" } } } } } }, "description": "Create a draft request for a person to price. Idempotency-Key is optional on own deployments. When provided, it must be a single nonblank header of 1..200 characters: same key and same body return the original order; different input returns 409. Keyed requests are atomic, reject unknown order/position fields, require a customer marked as a customer and a nonblank pn of at most 80 characters per line, default qty to 1 and require finite positive quantities. Keyed optional string lengths: external_ref 500, client_ref 120, note 2000, currency 3. Without the header, the legacy path uses a nonempty customer_id and 1..300 lines, skips lines without pn, defaults falsey qty to 1, defaults currency to USD, truncates currency to 3, client_ref to 60, note to 2000 and pn to 80; external_ref/description/brand are not retained by that path. Use keyed requests for retry-safe creation.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Optional own-deployment retry key; send a single nonblank value. See operation description for the keyed versus legacy behavior." } ] } }, "/api/v1/orders/{ref}": { "get": { "operationId": "getOrder", "tags": [ "Customer orders" ], "summary": "One order with its lines.", "x-deployment": "own", "x-required-scope": "orders:read", "parameters": [ { "name": "ref", "in": "path", "schema": { "type": "string" }, "description": "Record id or human-readable number.", "required": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/quotes": { "get": { "operationId": "listQuotes", "tags": [ "Sales documents" ], "summary": "Quotations sent.", "x-deployment": "own", "x-required-scope": "documents:read", "parameters": [ { "name": "updated_since", "in": "query", "schema": { "type": "string", "default": "" }, "description": "ISO 8601 date-time or Unix seconds; omitted means all history. For customers/orders only, opaque cursors are accepted when stable_cursor=true." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Results are clamped to 1\u2013200. A value of 0 uses the default of 50; invalid integer syntax returns 422." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_updated_since" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": {}, "no": {}, "kind": {}, "status": {}, "doc_date": {}, "due_date": {}, "net": {}, "total": {}, "currency": {}, "order_id": {}, "order_no": {}, "company_id": {}, "sent_at": {} }, "additionalProperties": true } }, "next_updated_since": { "type": [ "number", "null" ], "description": "Unix timestamp of the last record if a further page exists; otherwise null. Reuse as updated_since. Timestamp-only paging can skip records sharing the boundary timestamp." } } } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "description": "Non-draft sales documents, ordered by sent_at (falling back to created_at). The returned continuation is based on sent_at; documents without sent_at do not yield a usable continuation timestamp." } }, "/api/v1/invoices": { "get": { "operationId": "listInvoices", "tags": [ "Sales documents" ], "summary": "Tax invoices sent.", "x-deployment": "own", "x-required-scope": "documents:read", "parameters": [ { "name": "updated_since", "in": "query", "schema": { "type": "string", "default": "" }, "description": "ISO 8601 date-time or Unix seconds; omitted means all history. For customers/orders only, opaque cursors are accepted when stable_cursor=true." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Results are clamped to 1\u2013200. A value of 0 uses the default of 50; invalid integer syntax returns 422." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_updated_since" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": {}, "no": {}, "kind": {}, "status": {}, "doc_date": {}, "due_date": {}, "net": {}, "total": {}, "currency": {}, "order_id": {}, "order_no": {}, "company_id": {}, "sent_at": {} }, "additionalProperties": true } }, "next_updated_since": { "type": [ "number", "null" ], "description": "Unix timestamp of the last record if a further page exists; otherwise null. Reuse as updated_since. Timestamp-only paging can skip records sharing the boundary timestamp." } } } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "description": "Non-draft sales documents, ordered by sent_at (falling back to created_at). The returned continuation is based on sent_at; documents without sent_at do not yield a usable continuation timestamp." } }, "/api/v1/purchase-orders": { "get": { "operationId": "listPurchaseOrders", "tags": [ "Purchase orders" ], "summary": "Purchase orders, oldest change first.", "x-deployment": "own", "x-required-scope": "purchase-orders:read", "parameters": [ { "name": "updated_since", "in": "query", "schema": { "type": "string", "default": "" }, "description": "ISO 8601 date-time or Unix seconds; omitted means all history. For customers/orders only, opaque cursors are accepted when stable_cursor=true." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Results are clamped to 1\u2013200. A value of 0 uses the default of 50; invalid integer syntax returns 422." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_updated_since" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": {}, "no": {}, "status": {}, "currency": {}, "supplier_id": {}, "supplier": {}, "order_id": {}, "delivery_day": {}, "issued_at": {}, "updated_at": {} }, "additionalProperties": true } }, "next_updated_since": { "type": [ "number", "null" ], "description": "Unix timestamp of the last record if a further page exists; otherwise null. Reuse as updated_since. Timestamp-only paging can skip records sharing the boundary timestamp." } } } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/payments": { "get": { "operationId": "listPayments", "tags": [ "Payments" ], "summary": "Payments booked, oldest first.", "x-deployment": "own", "x-required-scope": "payments:read", "parameters": [ { "name": "updated_since", "in": "query", "schema": { "type": "string", "default": "" }, "description": "ISO 8601 date-time or Unix seconds; omitted means all history. For customers/orders only, opaque cursors are accepted when stable_cursor=true." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Results are clamped to 1\u2013200. A value of 0 uses the default of 50; invalid integer syntax returns 422." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_updated_since" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": {}, "kind": {}, "no": {}, "on_date": {}, "currency": {}, "amount": {}, "party_kind": {}, "party_id": {}, "document_id": {}, "created_at": {} }, "additionalProperties": true } }, "next_updated_since": { "type": [ "number", "null" ], "description": "Unix timestamp of the last record if a further page exists; otherwise null. Reuse as updated_since. Timestamp-only paging can skip records sharing the boundary timestamp." } } } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/accounting/accounts": { "get": { "operationId": "listAccounts", "tags": [ "Accounting" ], "summary": "The chart of accounts with balances.", "x-deployment": "own", "x-required-scope": "accounting:read", "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Accounting day (YYYY-MM-DD). Omitted accounts/trial-balance include all posted entries; omitted stock-valuation uses today. Balance-sheet requires a valid day." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/accounting/journals": { "get": { "operationId": "listJournals", "tags": [ "Accounting" ], "summary": "Journals, newest first.", "x-deployment": "own", "x-required-scope": "accounting:read", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Search text." }, { "name": "account", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Account code filter." }, { "name": "date_from", "in": "query", "schema": { "type": "string", "default": "" }, "description": "First day (YYYY-MM-DD), inclusive. Reports require a valid day; journals may omit it." }, { "name": "date_to", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Last day (YYYY-MM-DD), inclusive. Reports require a valid day; journals may omit it." }, { "name": "kind", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Journal source_kind filter." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 200 }, "description": "Results are clamped to 1\u20131000; this is a bounded list with no continuation cursor." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "operationId": "createJournal", "tags": [ "Accounting" ], "summary": "A manual journal. Never to a control account, never into a closed month.", "x-deployment": "own", "x-required-scope": "accounting:write", "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "memo", "lines" ], "properties": { "day": { "type": "string", "description": "YYYY-MM-DD; defaults to today." }, "memo": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "account": { "type": "string" }, "debit": { "type": "number" }, "credit": { "type": "number" }, "memo": { "type": "string" } } } } } } } } }, "description": "Post a balanced manual journal with a nonblank memo and at least two nonzero lines. Accounts must exist, be enabled and not be control accounts. Closed periods are refused. Returns the journal with lines, debit and credit totals. No idempotency key is implemented: after a timeout, reconcile the journal list before retrying to avoid a duplicate journal." } }, "/api/v1/accounting/journals/{ref}": { "get": { "operationId": "getJournal", "tags": [ "Accounting" ], "summary": "One journal with its lines.", "x-deployment": "own", "x-required-scope": "accounting:read", "parameters": [ { "name": "ref", "in": "path", "schema": { "type": "string" }, "description": "Record id or human-readable number.", "required": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/accounting/trial-balance": { "get": { "operationId": "getTrialBalance", "tags": [ "Accounting" ], "summary": "The trial balance on a day.", "x-deployment": "own", "x-required-scope": "accounting:read", "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Accounting day (YYYY-MM-DD). Omitted accounts/trial-balance include all posted entries; omitted stock-valuation uses today. Balance-sheet requires a valid day." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": {}, "currency": {}, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/accounting/profit-and-loss": { "get": { "operationId": "getProfitAndLoss", "tags": [ "Accounting" ], "summary": "Profit and loss between two days.", "x-deployment": "own", "x-required-scope": "accounting:read", "parameters": [ { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Required business date (YYYY-MM-DD); omission or an invalid date returns 400.", "required": true }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Required business date (YYYY-MM-DD); omission or an invalid date returns 400.", "required": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "currency": {}, "income": {}, "cost_of_sales": {}, "expenses": {}, "total_income": {}, "total_cost_of_sales": {}, "gross_profit": {}, "total_expenses": {}, "net_profit": {} }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/accounting/balance-sheet": { "get": { "operationId": "getBalanceSheet", "tags": [ "Accounting" ], "summary": "The balance sheet on a day.", "x-deployment": "own", "x-required-scope": "accounting:read", "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Required business date (YYYY-MM-DD); omission or an invalid date returns 400.", "required": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": {}, "currency": {}, "assets": {}, "liabilities": {}, "equity": {}, "total_assets": {}, "total_liabilities": {}, "total_equity": {}, "difference": {} }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/accounting/cash-flow": { "get": { "operationId": "getCashFlow", "tags": [ "Accounting" ], "summary": "Bank movements by what caused them.", "x-deployment": "own", "x-required-scope": "accounting:read", "parameters": [ { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Required business date (YYYY-MM-DD); omission or an invalid date returns 400.", "required": true }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Required business date (YYYY-MM-DD); omission or an invalid date returns 400.", "required": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": {}, "to": {}, "currency": {}, "lines": {}, "opening": {}, "net": {}, "closing": {} }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/accounting/tax-return": { "get": { "operationId": "getTaxReturn", "tags": [ "Accounting" ], "summary": "The tax return's boxes for a period.", "x-deployment": "own", "x-required-scope": "accounting:read", "parameters": [ { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Required business date (YYYY-MM-DD); omission or an invalid date returns 400.", "required": true }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Required business date (YYYY-MM-DD); omission or an invalid date returns 400.", "required": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": {}, "country": {}, "from": {}, "to": {}, "currency": {}, "boxes": {}, "output_tax": {}, "input_tax": {}, "net": {} }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/accounting/receivables": { "get": { "operationId": "listReceivables", "tags": [ "Accounting" ], "summary": "Open invoices and debit notes.", "x-deployment": "own", "x-required-scope": "accounting:read", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Search text." }, { "name": "overdue", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Include only overdue open items." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": {}, "currency": {}, "rows": {}, "on_account": {}, "total_base": {}, "overdue": {} }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/accounting/payables": { "get": { "operationId": "listPayables", "tags": [ "Accounting" ], "summary": "Open supplier bills.", "x-deployment": "own", "x-required-scope": "accounting:read", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Search text." }, { "name": "overdue", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Include only overdue open items." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": {}, "currency": {}, "rows": {}, "on_account": {}, "total_base": {}, "overdue": {} }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/accounting/stock-valuation": { "get": { "operationId": "getStockValuation", "tags": [ "Accounting" ], "summary": "Stock at cost, by part.", "x-deployment": "own", "x-required-scope": "accounting:read", "parameters": [ { "name": "as_of", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Accounting day (YYYY-MM-DD). Omitted accounts/trial-balance include all posted entries; omitted stock-valuation uses today. Balance-sheet requires a valid day." }, { "name": "q", "in": "query", "schema": { "type": "string", "default": "" }, "description": "Search text." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": {}, "currency": {}, "total": {}, "ledger": {}, "difference": {}, "parts": {}, "rows": {} }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "description": "Returns at most 500 part rows ordered by stock value. parts counts all matching parts and total covers all matches, including those beyond rows. There is no continuation cursor. as_of defaults to today." } }, "/api/v1/accounting/payments/{eid}/allocation": { "put": { "operationId": "allocatePayment", "tags": [ "Accounting" ], "summary": "Set one payment against several invoices or bills.", "x-deployment": "own", "x-required-scope": "accounting:write", "parameters": [ { "name": "eid", "in": "path", "schema": { "type": "string" }, "description": "Payment ledger entry id.", "required": true } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": {}, "currency": {}, "total": {}, "allocated": {}, "on_account": {}, "rows": {} }, "additionalProperties": true } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "target_kind": { "type": "string" }, "target_id": { "type": "string" }, "amount": { "type": "number" } } } } } } } } }, "description": "Replace the entire payment allocation. Omitted/empty rows put the payment on account. Nonzero amounts must be positive, within the open paper amount and payment total, for the same party and currency. kind/id are accepted aliases for target_kind/target_id." } }, "/api/v1/accounting/payment-runs": { "get": { "operationId": "listPaymentRuns", "tags": [ "Accounting" ], "summary": "Payment runs, newest first.", "x-deployment": "own", "x-required-scope": "accounting:read", "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "description": "Returns the latest 100 payment runs, newest first. There is no public limit parameter or continuation cursor." }, "post": { "operationId": "createPaymentRun", "tags": [ "Accounting" ], "summary": "A draft payment run. A person approves it and uploads its file to the bank.", "x-deployment": "own", "x-required-scope": "accounting:write", "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid input or business rule refusal. Missing accounting journals and payments are also reported as 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or ambiguous authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key does not have the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Requested customer/order does not exist (where applicable).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Accounting is unavailable, or an idempotency key conflicts with earlier input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Path/query validation failed (FastAPI validation detail response).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "503": { "description": "Database or integration schema is unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bill_ids": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "bill_id": { "type": "string" }, "amount": { "type": "number" } } } }, "day": { "type": "string", "description": "YYYY-MM-DD; defaults to today." }, "bank_account_id": { "type": "string" }, "format": { "type": "string", "enum": [ "pain001", "aba" ], "default": "pain001" }, "note": { "type": "string" } } } } } }, "description": "Create a draft payment run. Supply nonempty lines or bill_ids; nonempty lines take precedence. A line amount defaults to the open balance when omitted/zero. Bills must be open, not on another live run, pass supplier bank checks and share a currency. A person approves and uploads the bank file. Returns the run with lines, total and supported formats. No idempotency key is implemented: reconcile the payment-run list after a timeout before creating again." } }, "/api/v1/crm/deals/{ref}": { "get": { "operationId": "getDeal", "tags": [ "CRM deals" ], "summary": "Read a deal integration projection", "x-required-scope": "crm:read", "x-deployment": "own", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Deal id or deal number." } ], "responses": { "200": { "description": "Deal projection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deal" } } } }, "400": { "description": "Invalid input or external-order schema unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such deal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Deal already has a different external order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Database or integration schema unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/v1/crm/deals/{ref}/external-order": { "put": { "operationId": "attachExternalOrder", "tags": [ "CRM deals" ], "summary": "Attach a confirmed external order", "x-required-scope": "crm:write", "x-deployment": "own", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Deal id or deal number." } ], "responses": { "200": { "description": "Deal id and attached external_order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalOrderResult" } } } }, "400": { "description": "Invalid input or external-order schema unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Required scope missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such deal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Deal already has a different external order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Database or integration schema unavailable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "description": "Attach once; an exact retry is a no-op. A different existing external order returns 409. Requires the external-order storage schema.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalOrder" } } } } } } }, "components": { "securitySchemes": { "BearerKey": { "type": "http", "scheme": "bearer", "description": "Scoped Desk API key (tdk_...). Send exactly one authentication header." }, "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Alternative to Authorization: Bearer; do not send both." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "Page": { "type": "object", "required": [ "data", "next_updated_since" ], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "next_updated_since": { "type": [ "number", "string", "null" ], "description": "Null when there is no further page. A Unix timestamp by default; customers/orders return an opaque string when stable_cursor=true." } } }, "Items": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "Record": { "type": "object", "additionalProperties": true }, "ExternalOrder": { "type": "object", "properties": { "system": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Required and nonblank after trimming surrounding whitespace." }, "order_number": { "type": "string", "maxLength": 200, "minLength": 1, "description": "Required and nonblank after trimming surrounding whitespace." }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2000, "description": "HTTPS URL with a hostname and valid port, without user credentials, whitespace, control characters or backslashes. Surrounding whitespace is trimmed." } }, "required": [ "system", "order_number", "url" ] }, "ExternalOrderResult": { "type": "object", "properties": { "id": { "type": "string" }, "external_order": { "$ref": "#/components/schemas/ExternalOrder" } }, "required": [ "id", "external_order" ] }, "Deal": { "type": "object", "properties": { "id": { "type": "string" }, "company_id": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "stage": { "type": "string" }, "amount": { "type": "string", "description": "CRM amount text as entered on the deal; may be empty. This is not a numeric accounting total." }, "created_at": { "type": "number" }, "updated_at": { "type": "number" }, "ref": { "type": "string" }, "external_order": { "anyOf": [ { "$ref": "#/components/schemas/ExternalOrder" }, { "type": "null" } ] } }, "required": [ "id", "stage", "external_order" ] }, "Order": { "type": "object", "properties": { "id": { "type": "string" }, "no": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "client_ref": { "type": "string" }, "external_ref": { "type": "string" }, "customer": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 UTC timestamp, or null when no timestamp is recorded." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 UTC timestamp, or null when no timestamp is recorded." }, "lines": { "type": "array", "items": { "type": "object", "properties": { "pn": { "type": "string" }, "description": { "type": "string" }, "qty": { "type": "number" }, "price": { "type": [ "number", "null" ] }, "declined": { "type": "boolean" } }, "required": [] } } }, "required": [ "id", "no", "status", "lines" ] }, "OrderSummary": { "type": "object", "properties": { "id": { "type": "string" }, "no": { "type": "string" }, "status": { "type": "string" }, "currency": { "type": "string" }, "client_ref": { "type": "string" }, "company_id": { "type": [ "string", "null" ] }, "customer": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 UTC timestamp, or null when no timestamp is recorded." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 UTC timestamp, or null when no timestamp is recorded." } }, "required": [ "id", "updated_at" ] }, "Customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "legal_name": { "type": "string" }, "tax_no": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" }, "address1": { "type": "string" }, "postal": { "type": "string" }, "email": { "type": "string" }, "accounts_email": { "type": "string" }, "phone": { "type": "string" }, "website": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 UTC timestamp, or null when no timestamp is recorded." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601 UTC timestamp, or null when no timestamp is recorded." } }, "required": [ "id", "name", "updated_at" ] }, "RequestLine": { "type": "object", "properties": { "pn": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Must contain a non-whitespace character." }, "qty": { "type": "number", "exclusiveMinimum": 0, "default": 1 }, "description": { "type": "string" }, "brand": { "type": "string" } }, "required": [ "pn" ], "additionalProperties": false }, "OrderRequest": { "type": "object", "properties": { "customer_id": { "type": "string", "minLength": 1, "description": "Existing customer ID; must contain a non-whitespace character." }, "lines": { "type": "array", "minItems": 1, "maxItems": 300, "items": { "$ref": "#/components/schemas/RequestLine" } }, "currency": { "type": "string", "maxLength": 3 }, "note": { "type": "string", "maxLength": 2000 }, "client_ref": { "type": "string", "maxLength": 120 }, "external_ref": { "type": "string", "maxLength": 500 } }, "required": [ "customer_id", "lines" ], "additionalProperties": false, "examples": [ { "customer_id": "synthetic_customer", "external_ref": "synthetic_crm_42", "lines": [ { "pn": "EXAMPLE-123", "qty": 2 } ] } ] } } }, "x-own-webhooks": { "description": "Own-deployment webhooks are configured in Admin > Connections > Desk open API, not through a public machine subscription API. Hosted subscriptions use a separate owner-facing Integrations screen and delivery lifecycle. Changes are detected by scans; the first scan establishes a cursor without replaying history. Receive JSON POSTs at your HTTPS URL. Return 2xx within 10 seconds. Failed attempts retry after 60, 300, 1800, 7200, 21600 and 43200 seconds, then become failed. Administrators can retry unsent deliveries from the Connections log. Deduplicate by delivery id.", "events": [ "order.created", "order.updated", "quote.sent", "proforma.sent", "invoice.sent", "purchase_order.updated", "payment.received" ], "headers": { "X-Desk-Event": "Event name", "X-Desk-Delivery": "Delivery id", "X-Desk-Signature": "t=,v1=, over . followed by the raw body using the whsec_... secret. Check timestamp freshness and compare the signature securely." }, "payload": { "id": "delivery id", "event": "event name", "created_at": "ISO 8601 timestamp", "data": {} } }, "externalDocs": { "url": "https://docs.terraminedesk.ai/docs/agents.md", "description": "Agent integration guidance; select the contract for your deployment." }, "webhooks": { "order.created": { "post": { "operationId": "receiveOrderCreated", "parameters": [ { "name": "X-Desk-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Event type" }, { "name": "X-Desk-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery ID; deduplicate by payload id" }, { "name": "X-Desk-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=Unix seconds,v1=HMAC-SHA256(secret, timestamp + dot + raw body). Verify raw bytes and timestamp freshness." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "data" ], "properties": { "id": { "type": "string" }, "event": { "const": "order.created" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "no": { "type": "string" }, "status": { "type": "string" }, "client_ref": { "type": "string" }, "customer_id": { "type": [ "string", "null" ] } }, "required": [ "id", "no", "status", "client_ref", "customer_id" ] } } } } } }, "responses": { "200": { "description": "Accepted; any 2xx succeeds" }, "400": { "description": "Rejected; unsuccessful delivery attempts are retried with backoff." } }, "tags": [ "Own-deployment webhooks" ], "summary": "Receive order.created", "description": "Own-deployment scanned event, configured in Admin \u2192 Connections \u2192 Desk open API. Return any 2xx within 10 seconds. Unsuccessful attempts are retried with backoff; see x-own-webhooks for the schedule. Deduplicate by the signed envelope id." } }, "order.updated": { "post": { "operationId": "receiveOrderUpdated", "parameters": [ { "name": "X-Desk-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Event type" }, { "name": "X-Desk-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery ID; deduplicate by payload id" }, { "name": "X-Desk-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=Unix seconds,v1=HMAC-SHA256(secret, timestamp + dot + raw body). Verify raw bytes and timestamp freshness." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "data" ], "properties": { "id": { "type": "string" }, "event": { "const": "order.updated" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "no": { "type": "string" }, "status": { "type": "string" }, "client_ref": { "type": "string" }, "customer_id": { "type": [ "string", "null" ] } }, "required": [ "id", "no", "status", "client_ref", "customer_id" ] } } } } } }, "responses": { "200": { "description": "Accepted; any 2xx succeeds" }, "400": { "description": "Rejected; unsuccessful delivery attempts are retried with backoff." } }, "tags": [ "Own-deployment webhooks" ], "summary": "Receive order.updated", "description": "Own-deployment scanned event, configured in Admin \u2192 Connections \u2192 Desk open API. Return any 2xx within 10 seconds. Unsuccessful attempts are retried with backoff; see x-own-webhooks for the schedule. Deduplicate by the signed envelope id." } }, "quote.sent": { "post": { "operationId": "receiveQuoteSent", "parameters": [ { "name": "X-Desk-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Event type" }, { "name": "X-Desk-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery ID; deduplicate by payload id" }, { "name": "X-Desk-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=Unix seconds,v1=HMAC-SHA256(secret, timestamp + dot + raw body). Verify raw bytes and timestamp freshness." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "data" ], "properties": { "id": { "type": "string" }, "event": { "const": "quote.sent" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "no": { "type": "string" }, "order_id": { "type": "string" }, "currency": { "type": "string" }, "due_date": { "type": [ "string", "null" ] }, "total": { "type": "number" } }, "required": [ "id", "no", "order_id", "currency", "due_date", "total" ] } } } } } }, "responses": { "200": { "description": "Accepted; any 2xx succeeds" }, "400": { "description": "Rejected; unsuccessful delivery attempts are retried with backoff." } }, "tags": [ "Own-deployment webhooks" ], "summary": "Receive quote.sent", "description": "Own-deployment scanned event, configured in Admin \u2192 Connections \u2192 Desk open API. Return any 2xx within 10 seconds. Unsuccessful attempts are retried with backoff; see x-own-webhooks for the schedule. Deduplicate by the signed envelope id." } }, "proforma.sent": { "post": { "operationId": "receiveProformaSent", "parameters": [ { "name": "X-Desk-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Event type" }, { "name": "X-Desk-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery ID; deduplicate by payload id" }, { "name": "X-Desk-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=Unix seconds,v1=HMAC-SHA256(secret, timestamp + dot + raw body). Verify raw bytes and timestamp freshness." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "data" ], "properties": { "id": { "type": "string" }, "event": { "const": "proforma.sent" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "no": { "type": "string" }, "order_id": { "type": "string" }, "currency": { "type": "string" }, "due_date": { "type": [ "string", "null" ] }, "total": { "type": "number" } }, "required": [ "id", "no", "order_id", "currency", "due_date", "total" ] } } } } } }, "responses": { "200": { "description": "Accepted; any 2xx succeeds" }, "400": { "description": "Rejected; unsuccessful delivery attempts are retried with backoff." } }, "tags": [ "Own-deployment webhooks" ], "summary": "Receive proforma.sent", "description": "Own-deployment scanned event, configured in Admin \u2192 Connections \u2192 Desk open API. Return any 2xx within 10 seconds. Unsuccessful attempts are retried with backoff; see x-own-webhooks for the schedule. Deduplicate by the signed envelope id." } }, "invoice.sent": { "post": { "operationId": "receiveInvoiceSent", "parameters": [ { "name": "X-Desk-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Event type" }, { "name": "X-Desk-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery ID; deduplicate by payload id" }, { "name": "X-Desk-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=Unix seconds,v1=HMAC-SHA256(secret, timestamp + dot + raw body). Verify raw bytes and timestamp freshness." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "data" ], "properties": { "id": { "type": "string" }, "event": { "const": "invoice.sent" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "no": { "type": "string" }, "order_id": { "type": "string" }, "currency": { "type": "string" }, "due_date": { "type": [ "string", "null" ] }, "total": { "type": "number" } }, "required": [ "id", "no", "order_id", "currency", "due_date", "total" ] } } } } } }, "responses": { "200": { "description": "Accepted; any 2xx succeeds" }, "400": { "description": "Rejected; unsuccessful delivery attempts are retried with backoff." } }, "tags": [ "Own-deployment webhooks" ], "summary": "Receive invoice.sent", "description": "Own-deployment scanned event, configured in Admin \u2192 Connections \u2192 Desk open API. Return any 2xx within 10 seconds. Unsuccessful attempts are retried with backoff; see x-own-webhooks for the schedule. Deduplicate by the signed envelope id." } }, "purchase_order.updated": { "post": { "operationId": "receivePurchaseOrderUpdated", "parameters": [ { "name": "X-Desk-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Event type" }, { "name": "X-Desk-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery ID; deduplicate by payload id" }, { "name": "X-Desk-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=Unix seconds,v1=HMAC-SHA256(secret, timestamp + dot + raw body). Verify raw bytes and timestamp freshness." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "data" ], "properties": { "id": { "type": "string" }, "event": { "const": "purchase_order.updated" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "no": { "type": "string" }, "status": { "type": "string" }, "supplier_id": { "type": [ "string", "null" ] }, "delivery_day": { "type": [ "string", "null" ] } }, "required": [ "id", "no", "status", "supplier_id", "delivery_day" ] } } } } } }, "responses": { "200": { "description": "Accepted; any 2xx succeeds" }, "400": { "description": "Rejected; unsuccessful delivery attempts are retried with backoff." } }, "tags": [ "Own-deployment webhooks" ], "summary": "Receive purchase_order.updated", "description": "Own-deployment scanned event, configured in Admin \u2192 Connections \u2192 Desk open API. Return any 2xx within 10 seconds. Unsuccessful attempts are retried with backoff; see x-own-webhooks for the schedule. Deduplicate by the signed envelope id." } }, "payment.received": { "post": { "operationId": "receivePaymentReceived", "parameters": [ { "name": "X-Desk-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Event type" }, { "name": "X-Desk-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery ID; deduplicate by payload id" }, { "name": "X-Desk-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=Unix seconds,v1=HMAC-SHA256(secret, timestamp + dot + raw body). Verify raw bytes and timestamp freshness." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "data" ], "properties": { "id": { "type": "string" }, "event": { "const": "payment.received" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "no": { "type": "string" }, "on_date": { "type": "string" }, "currency": { "type": "string" }, "customer_id": { "type": [ "string", "null" ] }, "invoice_id": { "type": [ "string", "null" ] }, "amount": { "type": "number" } }, "required": [ "id", "no", "on_date", "currency", "customer_id", "invoice_id", "amount" ] } } } } } }, "responses": { "200": { "description": "Accepted; any 2xx succeeds" }, "400": { "description": "Rejected; unsuccessful delivery attempts are retried with backoff." } }, "tags": [ "Own-deployment webhooks" ], "summary": "Receive payment.received", "description": "Own-deployment scanned event, configured in Admin \u2192 Connections \u2192 Desk open API. Return any 2xx within 10 seconds. Unsuccessful attempts are retried with backoff; see x-own-webhooks for the schedule. Deduplicate by the signed envelope id." } } } }