{ "openapi": "3.1.0", "info": { "title": "Terramine hosted CRM\u2013ERP integration", "version": "1.0.0", "description": "Connect an external CRM or ERP to a Terramine workspace using scoped service keys and signed webhooks. This contract covers the six supported hosted operations. HTTPS, enabled modules and workspace entitlements are required. Hosted request bodies are limited to 128 KiB." }, "externalDocs": { "description": "CRM and ERP integration guide for AI agents", "url": "agents.md" }, "servers": [ { "url": "/", "description": "The customer's own workspace origin" } ], "paths": { "/api/v1/customers": { "get": { "operationId": "listCustomers", "tags": [ "ERP" ], "summary": "Find customers", "security": [ { "WorkspaceKey": [] } ], "x-required-scope": "customers:read", "parameters": [ { "name": "updated_since", "in": "query", "schema": { "type": "string" }, "description": "ISO UTC time, Unix seconds, or opaque next_updated_since cursor." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "stable_cursor", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Hosted workspaces always return composite cursors. Pass next_updated_since unchanged as updated_since, keep filters fixed, and stop when it is null. Set true for the same behavior on other supported hosts." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPage" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, unit or entitlement denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource or unavailable hosted route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or existing external reference conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the hosted body limit of 128 KiB." }, "422": { "description": "Invalid query parameter type." } } } }, "/api/v1/orders": { "get": { "operationId": "listOrders", "tags": [ "ERP" ], "summary": "List orders", "security": [ { "WorkspaceKey": [] } ], "x-required-scope": "orders:read", "parameters": [ { "name": "updated_since", "in": "query", "schema": { "type": "string" }, "description": "ISO UTC time, Unix seconds, or opaque next_updated_since cursor." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "stable_cursor", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Hosted workspaces always return composite cursors. Pass next_updated_since unchanged as updated_since, keep filters fixed, and stop when it is null. Set true for the same behavior on other supported hosts." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPage" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, unit or entitlement denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource or unavailable hosted route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or existing external reference conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the hosted body limit of 128 KiB." }, "422": { "description": "Invalid query parameter type." } } }, "post": { "operationId": "createDraftOrder", "tags": [ "ERP" ], "summary": "Create a draft order", "security": [ { "WorkspaceKey": [] } ], "x-required-scope": "orders:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "A stable ID for one quotation request, scoped to the service key grant. Retry with the same grant, key and payload to return the existing draft (201); different input returns 409. Use a new ID for a new quotation request, even on the same deal. Rotating the secret preserves receipts." } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, unit or entitlement denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource or unavailable hosted route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or existing external reference conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the hosted body limit of 128 KiB." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderRequest" } } } }, "description": "Validate the whole request and atomically create a draft. Reuse the same Idempotency-Key and payload for a retry. A different payload with that key returns 409." } }, "/api/v1/orders/{ref}": { "get": { "operationId": "getOrder", "tags": [ "ERP" ], "summary": "Read an order and its lines", "security": [ { "WorkspaceKey": [] } ], "x-required-scope": "orders:read", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, unit or entitlement denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource or unavailable hosted route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or existing external reference conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the hosted body limit of 128 KiB." } } } }, "/api/v1/crm/deals/{ref}": { "get": { "operationId": "getDeal", "tags": [ "CRM" ], "summary": "Read a CRM deal", "security": [ { "WorkspaceKey": [] } ], "x-required-scope": "crm:read", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deal" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, unit or entitlement denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource or unavailable hosted route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or existing external reference conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the hosted body limit of 128 KiB." } } } }, "/api/v1/crm/deals/{ref}/external-order": { "put": { "operationId": "attachExternalOrder", "tags": [ "CRM" ], "summary": "Attach an external order to a deal", "security": [ { "WorkspaceKey": [] } ], "x-required-scope": "crm:write", "parameters": [ { "name": "ref", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalOrderResult" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope, unit or entitlement denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown resource or unavailable hosted route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency or existing external reference conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Workspace unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request exceeds the hosted body limit of 128 KiB." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalOrder" } } } } } } }, "webhooks": { "crm.deal.stage_changed": { "post": { "operationId": "receiveStageChanged", "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": { "$ref": "#/components/schemas/StageChangedEvent" } } } }, "responses": { "200": { "description": "Accepted; any 2xx succeeds" }, "400": { "description": "Rejected; delivery is recorded" } } } }, "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": { "$ref": "#/components/schemas/QuoteSentEvent" } } } }, "responses": { "200": { "description": "Accepted; any 2xx succeeds" }, "400": { "description": "Rejected; delivery is recorded" } } } }, "integration.test": { "post": { "operationId": "receiveIntegrationTest", "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": { "$ref": "#/components/schemas/IntegrationTestEvent" } } } }, "responses": { "200": { "description": "Accepted; any 2xx succeeds" }, "400": { "description": "Rejected; delivery is recorded" } }, "summary": "Receive a synthetic webhook connection test", "description": "Sent only when the workspace owner tests one active subscription. Uses its signing secret and normal delivery log/replay. This is not a subscribable business event and contains no quote/deal IDs. Acknowledge after verifying the signature; do not run business automation." } } }, "components": { "securitySchemes": { "WorkspaceKey": { "type": "http", "scheme": "bearer", "description": "Owner-created workspace service key with explicit scopes." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "ExternalOrder": { "type": "object", "properties": { "system": { "type": "string", "maxLength": 100 }, "order_number": { "type": "string", "maxLength": 200 }, "url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2000 } }, "required": [ "system", "order_number", "url" ] }, "Deal": { "type": "object", "properties": { "id": { "type": "string" }, "company_id": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "stage": { "type": "string" }, "amount": { "type": "number" }, "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" ] }, "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" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "updated_at" ] }, "RequestLine": { "type": "object", "properties": { "pn": { "type": "string", "minLength": 1, "maxLength": 80 }, "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" }, "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 } ] } ] }, "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" }, "updated_at": { "type": "string" }, "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" }, "updated_at": { "type": "string" } }, "required": [ "id", "updated_at" ] }, "CustomerPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "next_updated_since": { "type": [ "number", "string", "null" ], "description": "Opaque composite timestamp and ID cursor. Pass unchanged as updated_since; null means no next page." } }, "required": [ "data", "next_updated_since" ] }, "OrderPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderSummary" } }, "next_updated_since": { "type": [ "number", "string", "null" ], "description": "Opaque composite timestamp and ID cursor. Pass unchanged as updated_since; null means no next page." } }, "required": [ "data", "next_updated_since" ] }, "ExternalOrderResult": { "type": "object", "properties": { "id": { "type": "string" }, "external_order": { "$ref": "#/components/schemas/ExternalOrder" } }, "required": [ "id", "external_order" ] }, "StageChangedEvent": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "const": "crm.deal.stage_changed" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "deal_id": { "type": "string" }, "from_stage": { "type": "string" }, "to_stage": { "type": "string" } }, "required": [ "deal_id", "from_stage", "to_stage" ] } }, "required": [ "id", "event", "created_at", "data" ] }, "QuoteSentEvent": { "type": "object", "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" } }, "required": [ "id", "no", "order_id" ] } }, "required": [ "id", "event", "created_at", "data" ] }, "IntegrationTestEvent": { "type": "object", "description": "Owner-requested synthetic delivery. Never treat this as a quote or deal transition. Verify and acknowledge it without creating or modifying a business record.", "properties": { "id": { "type": "string", "pattern": "^test_" }, "event": { "const": "integration.test" }, "test": { "const": true }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": false, "properties": { "test": { "const": true }, "subscription_id": { "type": "string" }, "subscribed_event": { "enum": [ "quote.sent", "crm.deal.stage_changed" ] }, "message": { "type": "string" } }, "required": [ "test", "subscription_id", "subscribed_event", "message" ] } }, "required": [ "id", "event", "test", "created_at", "data" ], "additionalProperties": false, "examples": [ { "id": "test_synthetic_example", "event": "integration.test", "test": true, "created_at": "2026-11-13T00:00:00Z", "data": { "test": true, "subscription_id": "synthetic_subscription", "subscribed_event": "quote.sent", "message": "Synthetic webhook test. No business record was created or changed." } } ] } } } }