{ "openapi": "3.1.0", "info": { "title": "GroundIT — Sales", "version": "0.1.0", "description": "Pre-delivery revenue (`sales`) — fsd-docs/15-sales-fsd.md, db-docs/18-sales.md, features-docs/14-sales-features.md. Web-portal-only (§W, Next.js); ends at a signed contract — `billing` (invoicing) and `work` (delivery) are downstream consumers reached by event/outbox, never a cross-schema join. `sales` never reads or writes `xc.tenant_cache` (ADR 0048).\n" }, "servers": [ { "url": "/api/v1" } ], "security": [ { "bearerJWT": [] } ], "tags": [ { "name": "sales", "description": "Pre-delivery revenue plane — fsd-docs/15 §W." }, { "name": "account", "description": "SAL-S02." }, { "name": "contact", "description": "SAL-S02." }, { "name": "enquiry", "description": "SAL-S01 (board), SAL-S03 (detail)." }, { "name": "pipeline-activity", "description": "SAL-S03 — append-only." }, { "name": "proposal", "description": "SAL-S04." }, { "name": "proposal-role-line", "description": "SAL-S04." }, { "name": "contract", "description": "SAL-S05." }, { "name": "license", "description": "SAL-S06." }, { "name": "license-usage-report", "description": "SAL-S06 — ingest is surface 5, apiKeyAuth + apiKeyHmac." } ], "paths": { "/accounts": { "get": { "operationId": "sales.account.list", "summary": "List accounts for the tenant", "tags": [ "sales", "account" ], "x-token": "sales.account.list", "x-realizes-features": [ "SAL-F01" ], "x-screens": [ "SAL-S01", "SAL-S02" ], "x-touches-entities": [ "sales.accounts" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "The account picker (`SAL-S01` new-enquiry) and account list (`SAL-S02`).", "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" }, { "$ref": "#/components/parameters/SortParam" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] } } ], "responses": { "200": { "description": "Page of accounts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "sales.account.create", "summary": "Create an account", "tags": [ "sales", "account" ], "x-token": "sales.account.create", "x-realizes-features": [ "SAL-F01" ], "x-screens": [ "SAL-S02" ], "x-touches-entities": [ "sales.accounts" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "The client-side identity `work.projects.client_name` never had (`SAL-S02`, ADR 0042). Flat v1 — no parent/subsidiary hierarchy, no de-duplication.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/AccountFields" }, { "required": [ "display_name" ] } ] } } } }, "responses": { "201": { "description": "Account created.", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/accounts/{id}": { "get": { "operationId": "sales.account.get", "summary": "Get an account (360)", "tags": [ "sales", "account" ], "x-token": "sales.account.get", "x-realizes-features": [ "SAL-F01" ], "x-screens": [ "SAL-S02" ], "x-touches-entities": [ "sales.accounts", "sales.contacts", "sales.enquiries", "sales.contracts", "sales.licenses" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "`SAL-S02` account 360 — header + the four tabs (Contacts, Enquiries, Contracts, Licenses). Finance and Project Manager hold this token **read-only**, scoped to accounts tied to their own contracts/projects.\n", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "Account.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "sales.account.update", "summary": "Update an account", "tags": [ "sales", "account" ], "x-token": "sales.account.update", "x-realizes-features": [ "SAL-F01" ], "x-screens": [ "SAL-S02" ], "x-touches-entities": [ "sales.accounts" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountFields" } } } }, "responses": { "200": { "description": "Account updated.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/accounts/{id}/archive": { "post": { "operationId": "sales.account.archive", "summary": "Archive an account", "tags": [ "sales", "account" ], "x-token": "sales.account.archive", "x-realizes-features": [ "SAL-F01" ], "x-screens": [ "SAL-S02" ], "x-touches-entities": [ "sales.accounts" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "`status → ARCHIVED`. Existing enquiries/contracts/licenses stay fully readable — only new-enquiry account selection excludes it.\n", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Account archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/accounts/{accountId}/contacts": { "post": { "operationId": "sales.contact.create", "summary": "Add a contact to an account", "tags": [ "sales", "contact" ], "x-token": "sales.contact.create", "x-realizes-features": [ "SAL-F01" ], "x-screens": [ "SAL-S02" ], "x-touches-entities": [ "sales.contacts" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ContactFields" }, { "required": [ "full_name" ] } ] } } } }, "responses": { "201": { "description": "Contact created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/contacts/{id}": { "patch": { "operationId": "sales.contact.update", "summary": "Update a contact", "tags": [ "sales", "contact" ], "x-token": "sales.contact.update", "x-realizes-features": [ "SAL-F01" ], "x-screens": [ "SAL-S02" ], "x-touches-entities": [ "sales.contacts" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactFields" } } } }, "responses": { "200": { "description": "Contact updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/enquiries": { "get": { "operationId": "sales.enquiry.list", "summary": "List enquiries (pipeline board)", "tags": [ "sales", "enquiry" ], "x-token": "sales.enquiry.list", "x-realizes-features": [ "SAL-F02" ], "x-screens": [ "SAL-S01" ], "x-touches-entities": [ "sales.enquiries" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "`SAL-S01` board read — grouped by `stage` client-side. Account owner scope: `x-rls-scope: self` overlay on `owner_id`, applied for the Sales/Account-owner persona; Sales manager reads unscoped.\n", "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" }, { "name": "stage", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ENQUIRY", "QUALIFIED", "PROPOSAL_SENT", "NEGOTIATION", "WON", "LOST" ] } }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "owner_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Page of enquiries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnquiryListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "sales.enquiry.create", "summary": "Create an enquiry", "tags": [ "sales", "enquiry" ], "x-token": "sales.enquiry.create", "x-realizes-features": [ "SAL-F02" ], "x-screens": [ "SAL-S01", "SAL-S02" ], "x-touches-entities": [ "sales.enquiries", "sales.pipeline_activity" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": "sales.enquiry.created", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "Lands at `stage = ENQUIRY` and writes the first `pipeline_activity` row. `source_license_id` is set only by the renewal job (`sales.license_usage_report.ingest`'s downstream cron, ADR 0048) — not settable on this endpoint.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EnquiryFields" }, { "required": [ "account_id", "title" ] } ] } } } }, "responses": { "201": { "description": "Enquiry created.", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enquiry" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/enquiries/{id}": { "get": { "operationId": "sales.enquiry.get", "summary": "Get an enquiry (detail + activity timeline)", "tags": [ "sales", "enquiry" ], "x-token": "sales.enquiry.get", "x-realizes-features": [ "SAL-F02" ], "x-screens": [ "SAL-S03" ], "x-touches-entities": [ "sales.enquiries", "sales.pipeline_activity", "sales.proposals" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "Enquiry detail — includes proposal-version summaries and the activity timeline.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnquiryDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "patch": { "operationId": "sales.enquiry.update", "summary": "Update an enquiry, including a stage transition", "tags": [ "sales", "enquiry" ], "x-token": "sales.enquiry.update", "x-realizes-features": [ "SAL-F02" ], "x-screens": [ "SAL-S01", "SAL-S03" ], "x-touches-entities": [ "sales.enquiries", "sales.pipeline_activity" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": "sales.enquiry.stage_changed", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "A `stage` change writes a `STAGE_CHANGE` `pipeline_activity` row in the same transaction. `stage = 'LOST'` requires `lost_reason` (`422` otherwise). `stage_entered_at` is stamped by the service, never client-supplied. `WON` is reached **only** through `sales.contract.sign` (§ contracts below) — supplying `stage: WON` directly on this endpoint is rejected.\n", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnquiryTransitionInput" } } } }, "responses": { "200": { "description": "Enquiry updated.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enquiry" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/enquiries/{enquiryId}/proposals": { "post": { "operationId": "sales.proposal.create", "summary": "Create the next proposal version for an enquiry", "tags": [ "sales", "proposal" ], "x-token": "sales.proposal.create", "x-realizes-features": [ "SAL-F03" ], "x-screens": [ "SAL-S03", "SAL-S04" ], "x-touches-entities": [ "sales.proposals" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "`version_no = max(existing)+1` (or `1`), status `DRAFT`. Superseding a `SENT` version is this same operation — the service marks the predecessor `SUPERSEDED` in the same transaction; there is no separate \"revise\" endpoint.\n", "parameters": [ { "name": "enquiryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalFields" } } } }, "responses": { "201": { "description": "Proposal version created.", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proposal" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/proposals/{id}": { "get": { "operationId": "sales.proposal.get", "summary": "Get a proposal version (composer)", "tags": [ "sales", "proposal" ], "x-token": "sales.proposal.get", "x-realizes-features": [ "SAL-F03" ], "x-screens": [ "SAL-S04" ], "x-touches-entities": [ "sales.proposals", "sales.proposal_role_lines" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "Proposal, with its role lines.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/proposals/{proposalId}/role-lines": { "post": { "operationId": "sales.proposal_role_line.create", "summary": "Add a per-role effort line to a DRAFT proposal", "tags": [ "sales", "proposal-role-line" ], "x-token": "sales.proposal_role_line.create", "x-realizes-features": [ "SAL-F03" ], "x-screens": [ "SAL-S04" ], "x-touches-entities": [ "sales.proposal_role_lines" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "`line_value = fte_or_hours × rate`, computed server-side, never client-supplied. Refused (`422`) once the parent proposal is not `DRAFT`.\n", "parameters": [ { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ProposalRoleLineFields" }, { "required": [ "role", "fte_or_hours", "period", "rate" ] } ] } } } }, "responses": { "201": { "description": "Role line created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalRoleLine" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/proposal-role-lines/{id}": { "patch": { "operationId": "sales.proposal_role_line.update", "summary": "Update a role line on a DRAFT proposal", "tags": [ "sales", "proposal-role-line" ], "x-token": "sales.proposal_role_line.update", "x-realizes-features": [ "SAL-F03" ], "x-screens": [ "SAL-S04" ], "x-touches-entities": [ "sales.proposal_role_lines" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalRoleLineFields" } } } }, "responses": { "200": { "description": "Role line updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalRoleLine" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "operationId": "sales.proposal_role_line.delete", "summary": "Remove a role line from a DRAFT proposal", "tags": [ "sales", "proposal-role-line" ], "x-token": "sales.proposal_role_line.delete", "x-realizes-features": [ "SAL-F03" ], "x-screens": [ "SAL-S04" ], "x-touches-entities": [ "sales.proposal_role_lines" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "204": { "description": "Role line removed." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/proposals/{id}/send": { "post": { "operationId": "sales.proposal.send", "summary": "Send a proposal — maker-checker'd above the discount band", "tags": [ "sales", "proposal" ], "x-token": "sales.proposal.send", "x-realizes-features": [ "SAL-F03" ], "x-screens": [ "SAL-S04" ], "x-touches-entities": [ "sales.proposals", "xc.approval_inbox", "sales.pipeline_activity" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": "sales.proposal.sent", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "`DRAFT → SENT`. If `discount_pct` exceeds the tenant's configured band, raises an `xc.approval_inbox` request type `DISCOUNT` (ADR 0027 §(e)/0042 §(f)) and answers `202` while *Awaiting approval* — the checker's decision is applied by this same endpoint under its own tokens (ADR 0027 §(d)), mirroring `billing.invoice.send`'s MC-1 pattern exactly (`14-billing.openapi.yaml`). Otherwise resolves directly to `200`. On resolution, `sent_at` is stamped and a `PROPOSAL_SENT` `pipeline_activity` row is written, and `sales.enquiries.stage` advances to `PROPOSAL_SENT` if it was earlier in the pipeline.\n", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Proposal sent — `status=SENT`, `sent_at` stamped.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proposal" } } } }, "202": { "description": "DISCOUNT approval request raised; proposal stays DRAFT until decided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/contracts": { "get": { "operationId": "sales.contract.list", "summary": "List contracts", "tags": [ "sales", "contract" ], "x-token": "sales.contract.list", "x-realizes-features": [ "SAL-F04" ], "x-screens": [ "SAL-S02", "SAL-S05" ], "x-touches-entities": [ "sales.contracts" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "SERVICES", "LICENSE" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "DRAFT", "PENDING_APPROVAL", "SIGNED", "TERMINATED" ] } } ], "responses": { "200": { "description": "Page of contracts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "sales.contract.create", "summary": "Create a DRAFT contract", "tags": [ "sales", "contract" ], "x-token": "sales.contract.create", "x-realizes-features": [ "SAL-F04" ], "x-screens": [ "SAL-S05" ], "x-touches-entities": [ "sales.contracts" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "`kind` is immutable once set. `winning_proposal_id` required when `kind = SERVICES` (`422` otherwise).\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ContractFields" }, { "required": [ "account_id", "kind", "value", "currency_code", "billing_type" ] } ] } } } }, "responses": { "201": { "description": "Contract created.", "headers": { "Location": { "$ref": "#/components/headers/Location" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contract" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/contracts/{id}": { "get": { "operationId": "sales.contract.get", "summary": "Get a contract", "tags": [ "sales", "contract" ], "x-token": "sales.contract.get", "x-realizes-features": [ "SAL-F04", "SAL-F05" ], "x-screens": [ "SAL-S05" ], "x-touches-entities": [ "sales.contracts" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "`project_id` is `null` for a real interval after `SIGNED` while the jobs-tier consumer creates the delivery project (ADR 0043) — the client polls or listens for `work.project.created_from_contract` rather than treating `null` as an error.\n", "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "Contract.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contract" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/contracts/{id}/submit": { "post": { "operationId": "sales.contract.submit", "summary": "Submit a DRAFT contract for approval", "tags": [ "sales", "contract" ], "x-token": "sales.contract.submit", "x-realizes-features": [ "SAL-F04" ], "x-screens": [ "SAL-S05" ], "x-touches-entities": [ "sales.contracts", "xc.approval_inbox" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "`DRAFT → PENDING_APPROVAL`. Raises an `xc.approval_inbox` request type `CONTRACT` (ADR 0027 §(e)/0042 §(f)).", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "202": { "description": "CONTRACT approval request raised; contract is PENDING_APPROVAL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalAccepted" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/contracts/{id}/sign": { "post": { "operationId": "sales.contract.sign", "summary": "Apply the CONTRACT approval decision — the win flow", "tags": [ "sales", "contract" ], "x-token": "sales.contract.sign", "x-realizes-features": [ "SAL-F04", "SAL-F05" ], "x-screens": [ "SAL-S05" ], "x-touches-entities": [ "sales.contracts", "sales.licenses", "work.projects" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "async", "x-emits-event": "sales.contract.won", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "Applies the checker's decision under this module's own token — the maker's token cannot also sign (`403 MAKER_EQUALS_CHECKER`, ADR 0027 §(d)). `PENDING_APPROVAL → SIGNED`, `signed_at` stamped. For `kind = SERVICES` this is the transaction that appends the `sales.contract.won` outbox event consumed by the jobs-tier project-creation path (ADR 0043(a)) — `project_id` stays `null` in the immediate response and is stamped asynchronously; poll `sales.contract.get` or listen for `work.project.created_from_contract`. For `kind = LICENSE`, the same transaction writes the `sales.licenses` row **synchronously** (ADR 0048) and the response's `license_id` is populated immediately — no async wait for a license.\n", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Contract signed. `project_id` (SERVICES) is null until the async consumer stamps it; `license_id` (LICENSE) is populated immediately.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contract" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/contracts/{id}/terminate": { "post": { "operationId": "sales.contract.terminate", "summary": "Terminate a SIGNED contract", "tags": [ "sales", "contract" ], "x-token": "sales.contract.terminate", "x-realizes-features": [ "SAL-F04" ], "x-screens": [ "SAL-S05" ], "x-touches-entities": [ "sales.contracts" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": "sales.contract.terminated", "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "description": "`SIGNED → TERMINATED`. **No un-win path** — a delivery project already created by this contract is untouched (ADR 0043, known residue); this operation records the commercial fact only.\n", "parameters": [ { "$ref": "#/components/parameters/PathId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Contract terminated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contract" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/licenses": { "get": { "operationId": "sales.license.list", "summary": "List licenses (dashboard)", "tags": [ "sales", "license" ], "x-token": "sales.license.list", "x-realizes-features": [ "SAL-F06", "SAL-F07" ], "x-screens": [ "SAL-S06" ], "x-touches-entities": [ "sales.licenses" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" }, { "$ref": "#/components/parameters/PageBefore" }, { "name": "account_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "EXPIRING", "EXPIRED", "CANCELLED" ] } } ], "responses": { "200": { "description": "Page of licenses, each with its latest seats-in-use (computed, not stored).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/licenses/{id}": { "get": { "operationId": "sales.license.get", "summary": "Get a license, with its usage-report trend", "tags": [ "sales", "license" ], "x-token": "sales.license.get", "x-realizes-features": [ "SAL-F06" ], "x-screens": [ "SAL-S06" ], "x-touches-entities": [ "sales.licenses", "sales.license_usage_reports" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": false, "x-entitlement": "sales", "x-provisional": null, "parameters": [ { "$ref": "#/components/parameters/PathId" } ], "responses": { "200": { "description": "License detail.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/licenses/{licenseId}/usage-reports": { "get": { "operationId": "sales.license_usage_report.list", "summary": "List usage reports for a license (append-only, newest first)", "tags": [ "sales", "license-usage-report" ], "x-token": "sales.license_usage_report.list", "x-realizes-features": [ "SAL-F06" ], "x-screens": [ "SAL-S06" ], "x-touches-entities": [ "sales.license_usage_reports" ], "x-idempotent": false, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "sales", "x-provisional": null, "parameters": [ { "name": "licenseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageAfter" } ], "responses": { "200": { "description": "Page of usage reports.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseUsageReportListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/licenses/{licenseId}/usage-reports/ingest": { "post": { "operationId": "sales.license_usage_report.ingest", "summary": "Report metered usage — external API-key callers only (surface 5)", "tags": [ "sales", "license-usage-report" ], "x-token": "sales.license_usage.write", "x-realizes-features": [ "SAL-F06" ], "x-screens": [], "x-touches-entities": [ "sales.license_usage_reports" ], "x-idempotent": true, "x-market": "both", "x-sync-async": "sync", "x-emits-event": null, "x-rls-scope": "tenant", "x-append-only": true, "x-entitlement": "sales", "x-provisional": null, "description": "**Surface 5, not surface 1** ([`11-surface-sales-and-external-access.md`](../../11-surface-sales-and-external-access.md)). Requires an API key scoped to `sales.license_usage.write` **and mandatory HMAC request signing** (`apiKeyHmac`, not optional) — a forged report understates seats in use and has direct billing consequences for the licensing tenant (ADR 0047/0048). Never `bearerJWT`. Append-only — a correction is a new row, never an update to a prior report.\n", "security": [ { "apiKeyAuth": [ "sales.license_usage.write" ], "apiKeyHmac": [] } ], "parameters": [ { "name": "licenseId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "format": "date-time" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/LicenseUsageReportFields" }, { "required": [ "seats_in_use", "reported_at" ] } ] } } } }, "responses": { "201": { "description": "Usage report recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseUsageReport" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "components": { "schemas": { "AccountFields": { "type": "object", "properties": { "display_name": { "type": "string", "minLength": 2, "maxLength": 200 }, "industry": { "type": "string", "nullable": true }, "website": { "type": "string", "format": "uri", "nullable": true }, "account_owner_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] } } }, "Account": { "allOf": [ { "$ref": "#/components/schemas/AccountFields" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "AccountDetail": { "allOf": [ { "$ref": "#/components/schemas/Account" }, { "type": "object", "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "enquiries": { "type": "array", "items": { "$ref": "#/components/schemas/Enquiry" } }, "contracts": { "type": "array", "items": { "$ref": "#/components/schemas/Contract" } }, "licenses": { "type": "array", "items": { "$ref": "#/components/schemas/License" } } } } ] }, "AccountListResponse": { "allOf": [ { "$ref": "#/components/schemas/CursorPage" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } } } ] }, "ContactFields": { "type": "object", "properties": { "full_name": { "type": "string", "minLength": 2, "maxLength": 200 }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "is_primary": { "type": "boolean", "default": false }, "status": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] } } }, "Contact": { "allOf": [ { "$ref": "#/components/schemas/ContactFields" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "account_id": { "type": "string", "format": "uuid" } } } ] }, "EnquiryFields": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid", "nullable": true }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "owner_id": { "type": "string", "format": "uuid", "nullable": true }, "estimated_value": { "$ref": "#/components/schemas/Money" }, "source": { "type": "string", "nullable": true } } }, "EnquiryTransitionInput": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "ENQUIRY", "QUALIFIED", "PROPOSAL_SENT", "NEGOTIATION", "LOST" ] }, "lost_reason": { "type": "string", "nullable": true, "description": "required when stage = LOST" }, "owner_id": { "type": "string", "format": "uuid", "nullable": true } } }, "Enquiry": { "allOf": [ { "$ref": "#/components/schemas/EnquiryFields" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enquiry_no": { "type": "string" }, "stage": { "type": "string", "enum": [ "ENQUIRY", "QUALIFIED", "PROPOSAL_SENT", "NEGOTIATION", "WON", "LOST" ] }, "stage_entered_at": { "type": "string", "format": "date-time" }, "source_license_id": { "type": "string", "format": "uuid", "nullable": true }, "lost_reason": { "type": "string", "nullable": true } } } ] }, "EnquiryDetail": { "allOf": [ { "$ref": "#/components/schemas/Enquiry" }, { "type": "object", "properties": { "proposals": { "type": "array", "items": { "$ref": "#/components/schemas/Proposal" } }, "activity": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineActivity" } } } } ] }, "EnquiryListResponse": { "allOf": [ { "$ref": "#/components/schemas/CursorPage" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Enquiry" } } } } ] }, "PipelineActivity": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enquiry_id": { "type": "string", "format": "uuid" }, "activity_type": { "type": "string", "enum": [ "STAGE_CHANGE", "OWNER_CHANGE", "PROPOSAL_SENT", "PROJECT_CREATED", "NOTE" ] }, "payload": { "type": "object" }, "note": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid", "nullable": true } } }, "ProposalFields": { "type": "object", "properties": { "discount_pct": { "type": "number", "minimum": 0, "maximum": 1, "nullable": true }, "valid_until": { "type": "string", "format": "date", "nullable": true }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 } } }, "Proposal": { "allOf": [ { "$ref": "#/components/schemas/ProposalFields" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "enquiry_id": { "type": "string", "format": "uuid" }, "version_no": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "DRAFT", "SENT", "SUPERSEDED", "WON", "LOST" ] }, "total_value": { "$ref": "#/components/schemas/Money" }, "sent_at": { "type": "string", "format": "date-time", "nullable": true } } } ] }, "ProposalDetail": { "allOf": [ { "$ref": "#/components/schemas/Proposal" }, { "type": "object", "properties": { "role_lines": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalRoleLine" } } } } ] }, "ProposalRoleLineFields": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 100 }, "fte_or_hours": { "type": "number", "exclusiveMinimum": 0 }, "period": { "type": "string", "enum": [ "WEEKLY", "MONTHLY", "TOTAL" ] }, "rate": { "$ref": "#/components/schemas/Money" } } }, "ProposalRoleLine": { "allOf": [ { "$ref": "#/components/schemas/ProposalRoleLineFields" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "proposal_id": { "type": "string", "format": "uuid" }, "line_value": { "$ref": "#/components/schemas/Money" } } } ] }, "ContractFields": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "winning_proposal_id": { "type": "string", "format": "uuid", "nullable": true, "description": "required for kind = SERVICES" }, "kind": { "type": "string", "enum": [ "SERVICES", "LICENSE" ] }, "value": { "$ref": "#/components/schemas/Money" }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3 }, "billing_type": { "type": "string", "description": "aligned to work.projects.billing_type" }, "term_start_date": { "type": "string", "format": "date", "nullable": true }, "term_end_date": { "type": "string", "format": "date", "nullable": true } } }, "Contract": { "allOf": [ { "$ref": "#/components/schemas/ContractFields" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "contract_no": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "PENDING_APPROVAL", "SIGNED", "TERMINATED" ] }, "signed_at": { "type": "string", "format": "date-time", "nullable": true }, "project_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ref→work.projects, SERVICES only, stamped async" }, "license_id": { "type": "string", "format": "uuid", "nullable": true, "description": "LICENSE only, stamped synchronously on sign" } } } ] }, "ContractListResponse": { "allOf": [ { "$ref": "#/components/schemas/CursorPage" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contract" } } } } ] }, "LicenseFields": { "type": "object", "properties": { "product": { "type": "string" }, "plan": { "type": "string" }, "seats": { "type": "integer", "exclusiveMinimum": 0 }, "entitlements": { "type": "object" }, "starts_on": { "type": "string", "format": "date" }, "ends_on": { "type": "string", "format": "date" } } }, "License": { "allOf": [ { "$ref": "#/components/schemas/LicenseFields" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "contract_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "ACTIVE", "EXPIRING", "EXPIRED", "CANCELLED" ] }, "latest_seats_in_use": { "type": "integer", "description": "computed read — no materialized column" } } } ] }, "LicenseDetail": { "allOf": [ { "$ref": "#/components/schemas/License" }, { "type": "object", "properties": { "usage_trend": { "type": "array", "items": { "$ref": "#/components/schemas/LicenseUsageReport" } }, "renewal_enquiry_id": { "type": "string", "format": "uuid", "nullable": true } } } ] }, "LicenseListResponse": { "allOf": [ { "$ref": "#/components/schemas/CursorPage" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/License" } } } } ] }, "LicenseUsageReportFields": { "type": "object", "properties": { "seats_in_use": { "type": "integer", "minimum": 0 }, "usage_counters": { "type": "object" }, "reported_at": { "type": "string", "format": "date-time" } } }, "LicenseUsageReport": { "allOf": [ { "$ref": "#/components/schemas/LicenseUsageReportFields" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "license_id": { "type": "string", "format": "uuid" }, "api_key_id": { "type": "string", "format": "uuid", "description": "ref→xc.api_keys, redacted to prefix+last4 on read" }, "created_at": { "type": "string", "format": "date-time" } } } ] }, "LicenseUsageReportListResponse": { "allOf": [ { "$ref": "#/components/schemas/CursorPage" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LicenseUsageReport" } } } } ] }, "ApprovalAccepted": { "type": "object", "description": "Shared 202 shape for a raised xc.approval_inbox request — mirrors billing.invoice.send.", "properties": { "approval_request_id": { "type": "string", "format": "uuid" }, "request_type": { "type": "string", "enum": [ "DISCOUNT", "CONTRACT" ] }, "status": { "type": "string", "enum": [ "PENDING" ] } } }, "CursorPage": { "type": "object", "description": "Generic cursor-pagination envelope. List operations compose it via allOf to type `data`, e.g. `allOf: [ {$ref CursorPage}, { properties: { data: { items: {$ref Employee} } } } ]`.\n", "required": [ "data", "page" ], "properties": { "data": { "type": "array", "items": {} }, "page": { "type": "object", "required": [ "has_more" ], "properties": { "next_cursor": { "type": [ "string", "null" ] }, "prev_cursor": { "type": [ "string", "null" ] }, "has_more": { "type": "boolean" }, "total_est": { "type": [ "integer", "null" ], "description": "Optional, capped, APPROXIMATE row estimate for grid \"X of Z\" display only — never an exact COUNT(*) on large tables (attend.attendance_records, xc.notifications, audit.*).\n" } } } } }, "Money": { "type": "object", "description": "Exact decimal money (db-docs/00 §6). `amount` is a STRING so float never enters the wire.", "required": [ "amount", "currency_code" ], "additionalProperties": false, "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,2})?$", "description": "numeric(18,2) as a string, e.g. \"45000.00\"." }, "currency_code": { "$ref": "#/components/schemas/CurrencyCode" } } }, "Problem": { "type": "object", "description": "RFC 9457 problem detail (application/problem+json). The platform-wide error envelope (03 §1).", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri", "default": "about:blank", "description": "Problem-type URI." }, "title": { "type": "string", "description": "Short, human-readable summary (stable per type)." }, "status": { "type": "integer", "description": "HTTP status code, duplicated for convenience." }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence." }, "instance": { "type": "string", "description": "URI reference for this specific occurrence." }, "code": { "$ref": "#/components/schemas/ErrorCode" }, "correlation_id": { "$ref": "#/components/schemas/Uuid" } } }, "ValidationProblem": { "description": "422 field-level validation failure; extends Problem with a per-field error array. `detail` is ALWAYS present on a 422 (#1251) and is the human summary of `errors[]`: one offending field renders as `\": \"` (`withholding_amount: is required for an India entity`), several as `\"N fields were refused: a, b, c.\"`, capped at five names. It is display copy derived from members already in the same body — clients keep branching on `code` and mapping `errors[].pointer` back to a control, never parsing this sentence.\n", "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "type": "object", "required": [ "detail", "errors" ], "properties": { "detail": { "type": "string", "description": "Human summary of `errors[]`, always populated on a 422 so a client never has to fall back to generic copy for the one status that names a fixable field.\n", "example": "withholding_amount: is required for an India entity" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "pointer", "rule" ], "properties": { "pointer": { "type": "string", "description": "JSON Pointer to the offending field, e.g. /claim_amount" }, "rule": { "type": "string", "enum": [ "required", "format", "length", "range", "cross-field", "async-server", "consent-gated", "uniqueness-business", "not_found" ], "description": "FSD validation taxonomy rule (fsd-docs/00 §8.2). `not_found` is the server-side-lookup arm: a body field that REFERENCES another resource (e.g. `project_id` on a work entry) and did not resolve for this caller. It is reported here, under the field's pointer, and NOT as a 404 — the request addresses its own resource, so the failure belongs on the form field the client can actually fix (#805).\n" }, "message": { "type": "string" } } } } } } ] }, "Uuid": { "type": "string", "format": "uuid", "description": "UUIDv7 surrogate primary key (db-docs/00 §3). Never the business identifier." }, "CurrencyCode": { "type": "string", "enum": [ "INR", "SAR" ], "description": "ISO-4217. A legal entity operates in a single currency (db-docs/00 §6)." }, "ErrorCode": { "type": "string", "description": "Machine-stable error code (paired with the HTTP status; drives client handling, not display copy).", "enum": [ "VALIDATION_FAILED", "IDEMPOTENCY_KEY_REUSE", "VERSION_CONFLICT", "PRECONDITION_REQUIRED", "MAKER_EQUALS_CHECKER", "STEP_UP_REQUIRED", "CONSENT_REQUIRED", "TOKEN_DENIED", "SCOPE_DENIED", "OWNERSHIP_DENIED", "STATE_TRANSITION_INVALID", "FACE_MISMATCH", "FACE_VERIFICATION_REQUIRED", "WITHHOLDING_REVIEW_REQUIRED", "FEATURE_NOT_IN_PLAN", "PLAN_LIMIT_EXCEEDED", "TENANT_PAST_DUE", "TENANT_SUSPENDED", "TENANT_CANCELLED", "RATE_LIMITED", "NOT_FOUND" ] } }, "parameters": { "PageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Max items per page. Cursor pagination only (03 §2); offset pagination is rejected (ADR 0015).", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "PageAfter": { "name": "page[after]", "in": "query", "required": false, "description": "Opaque forward keyset cursor (from a prior page's `page.next_cursor`).", "schema": { "type": "string" } }, "PageBefore": { "name": "page[before]", "in": "query", "required": false, "description": "Opaque backward keyset cursor (from a prior page's `page.prev_cursor`).", "schema": { "type": "string" } }, "SortParam": { "name": "sort", "in": "query", "required": false, "description": "Comma-separated sort keys; leading `-` = descending. Each key MUST be in the operation's documented sort whitelist (free-form sort is rejected so the keyset cursor stays stable).\n", "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated unique key. REQUIRED on every mutation (this round tightens ADR 0015's \"platform + retryable mutations\" floor to ALL mutations for uniformity — offline punch/leave sync depends on it). Scoped (tenant, principal, route, key); a replay within the ~24h window returns the stored response with `Idempotency-Replayed: true`; the same key with a different body → 409 IDEMPOTENCY_KEY_REUSE (04 §1).\n", "schema": { "type": "string", "minLength": 8, "maxLength": 255 } }, "PathId": { "name": "id", "in": "path", "required": true, "description": "UUIDv7 surrogate key of the target resource. Business numbers (`employee_no`, `claim_no`, …) are read-model fields, never path keys.", "schema": { "$ref": "#/components/schemas/Uuid" } }, "IfMatch": { "name": "If-Match", "in": "header", "required": true, "description": "Optimistic-concurrency precondition for mutating a VERSIONED mutable entity (db-docs/00 §5 applies `version` where concurrent edits are likely). Value is the entity's current ETag (the row `version`). Absent → 428; stale → 412 (04 §2). N/A for append-only entities and for unversioned low-contention entities (their update ops simply omit this parameter).\n", "schema": { "type": "string" } } }, "responses": { "Unauthorized": { "description": "Missing, expired, or invalid session token (no authenticated principal).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "Authenticated but denied — permission token not granted, out of scope (self/team/branch), not the owner, tenant suspended, or an MC-2 operation without a fresh step-up challenge. `code` ∈ TOKEN_DENIED | SCOPE_DENIED | OWNERSHIP_DENIED | MAKER_EQUALS_CHECKER | STEP_UP_REQUIRED | CONSENT_REQUIRED | TENANT_SUSPENDED. A plan feature-flag being off is 402 FEATURE_NOT_IN_PLAN, not 403 (see PaymentRequired).\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TooManyRequests": { "description": "Per-principal/route rate limit exceeded.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Conflict": { "description": "Idempotency-key reuse with a different body, an invalid state transition, or a uniqueness/business-rule violation (fsd 00 §8.2). For database-backed uniqueness rules, detail names the exact violated rule; unmapped constraints are not collapsed into a generic 409.\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "UnprocessableEntity": { "description": "Field-level validation failed. The body carries both `errors[]` (per-field, pointer-addressed) and a `detail` summarising them — never an empty `detail` (#1251).\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" }, "examples": { "singleField": { "summary": "One refused field — `detail` names it", "value": { "type": "about:blank", "title": "Unprocessable Entity", "status": 422, "code": "VALIDATION_FAILED", "detail": "withholding_amount: is required for an India entity", "errors": [ { "pointer": "/withholding_amount", "rule": "required", "message": "is required for an India entity" } ] } }, "severalFields": { "summary": "Several refused fields — `detail` counts and names them", "value": { "type": "about:blank", "title": "Unprocessable Entity", "status": 422, "code": "VALIDATION_FAILED", "detail": "2 fields were refused: effective_from, cap_amount.amount.", "errors": [ { "pointer": "/effective_from", "rule": "cross-field", "message": "Overlaps an existing version." }, { "pointer": "/cap_amount/amount", "rule": "range", "message": "Must be a non-negative decimal string." } ] } } } } } }, "NotFound": { "description": "Resource does not exist OR is masked by RLS (tenant/self/team/branch scope) — the API does not distinguish, so existence is never confirmed across a scope boundary (02 §4 disclosure posture).\n", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PreconditionFailed": { "description": "If-Match / ETag mismatch — the row changed since it was read (412, VERSION_CONFLICT).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PreconditionRequired": { "description": "If-Match header absent on a mutation of a versioned mutable entity (428).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "headers": { "Location": { "description": "URI of the created/affected resource.", "schema": { "type": "string", "format": "uri-reference" } }, "ETag": { "description": "Strong validator of the row `version` (e.g. `\"v7\"`). Use as `If-Match` on the next mutation.", "schema": { "type": "string" } }, "RetryAfter": { "description": "Seconds to wait before retrying (on 429 / 503).", "schema": { "type": "integer" } } } } }