{"openapi":"3.1.0","info":{"title":"Viacle API","version":"1.0.0","description":"The authoritative contract for Purchase Objects: preserve source evidence and field provenance, resolve commercial identity, record lifecycle events and corrections, and deliver trusted purchase context through APIs and webhooks. Domain capabilities such as AP, freight, tax, fraud, and close readiness build on these primitives.","contact":{"email":"api@viacle.com"}},"servers":[{"url":"/api/v1","description":"Current environment"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Purchases","description":"Core purchase object lifecycle","x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"]},{"name":"Entities","description":"Person and business identity records","x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"]},{"name":"Merchants","description":"Merchant graph nodes","x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"]},{"name":"Products","description":"Product graph nodes","x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"]},{"name":"Auth","description":"API key management and OAuth 2.0","x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"]},{"name":"Webhooks","description":"Webhook endpoint management and delivery logs","x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"]},{"name":"Streaming","description":"Server-Sent Events for real-time purchase events","x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"]},{"name":"Commercial Events","description":"Versioned Commercial Context records composed from immutable source facts, deterministic projections, evidence, relationships, corrections, and history","x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"]},{"name":"Reconciliation","description":"Actionable cross-source reconciliation queue and human match decisions","x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"]},{"name":"Connectors","description":"Data source integrations (184 types)","x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"]},{"name":"Expenses","description":"Non-receipt expense creation (mileage, per-diem)","x-viacle-exposure":"experimental","x-viacle-audience":["evaluation-only"]},{"name":"Policies","description":"Expense compliance policy management","x-viacle-exposure":"experimental","x-viacle-audience":["evaluation-only"]},{"name":"Tax","description":"TIN-scoped tax aggregation and 1099 reporting","x-viacle-exposure":"vertical-adapter","x-viacle-audience":["institutional-distributor","domain-system"]},{"name":"FDX","description":"Financial Data Exchange v6.5 — consents, accounts, transactions","x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"]},{"name":"Compliance","description":"Audit event log and export","x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"]},{"name":"Ownership","description":"Product ownership records","x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"]},{"name":"Intelligence","description":"Purchase intelligence signals — recall, subscription, warranty, tax treatment, vendor risk, related purchases","x-viacle-exposure":"experimental","x-viacle-audience":["evaluation-only"]},{"name":"QuickBooks","description":"QuickBooks Online chart of accounts sync and GL code mapping for connected portal accounts","x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"]},{"name":"Commercial","description":"Commercial AP intelligence — GL code suggestion, PO match, exception flags, auto-codeability, 1099 reporting signals, AP automation rules, close readiness","x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"]},{"name":"Commercial Cases","description":"Authorized, disclosure-safe commercial case projections and decisions","x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"]},{"name":"Consumer Commercial Cases","description":"Consumer-controlled grants for statement-derived commercial case projections","x-viacle-exposure":"private-application","x-viacle-audience":["viacle-application"]},{"name":"Airwallex Deliveries","description":"Queued Commercial Case delivery lifecycle for Airwallex targets","x-viacle-exposure":"partner-only","x-viacle-audience":["approved-partner"]},{"name":"Widget","description":"Hosted embed session management — create short-lived JWTs for the Viacle purchase viewer iframe","x-viacle-exposure":"private-application","x-viacle-audience":["viacle-application"]}],"paths":{"/commercial-cases":{"get":{"tags":["Commercial Cases"],"summary":"List disclosure-safe Commercial Cases","security":[{"BearerAuth":["purchases:read"]},{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"Cursor-paginated Commercial Cases","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCasePage"},"examples":{"first_page":{"value":{"data":[{"id":"ccase_123","caseReference":"CASE-2026-001","caseType":"accounts_payable","lifecycleState":"open","resolutionState":"unresolved","completenessState":"complete","createdAt":"2026-01-01T00:00:00.000Z","updatedAt":"2026-01-01T00:00:00.000Z"}],"next_cursor":null}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-cases/projections/{projectionKey}":{"get":{"tags":["Commercial Cases"],"summary":"Get Commercial Case projection status","security":[{"BearerAuth":["purchases:read"]},{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"$ref":"#/components/parameters/ProjectionKey"}],"responses":{"200":{"description":"Projection status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCaseProjection"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-cases/projections/{projectionKey}/retry":{"post":{"tags":["Commercial Cases"],"summary":"Retry a Commercial Case projection","security":[{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"$ref":"#/components/parameters/ProjectionKey"}],"responses":{"202":{"description":"Projection retry accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCaseProjection"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-cases/{caseId}":{"get":{"tags":["Commercial Cases"],"summary":"Get a disclosure-safe Commercial Case","security":[{"BearerAuth":["purchases:read"]},{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"$ref":"#/components/parameters/CommercialCaseId"}],"responses":{"200":{"description":"Authorized case detail; source payload metadata is never disclosed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCaseDetail"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-cases/{caseId}/ppr":{"get":{"tags":["Commercial Cases"],"summary":"Generate an authorized Portable Purchase Record","description":"Creates PPR 1.0.0 only from the caller-authorized, disclosure-safe case projection. Restricted assertions and unavailable objects are excluded.","security":[{"BearerAuth":["purchases:read"]},{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"$ref":"#/components/parameters/CommercialCaseId"},{"name":"version","in":"query","schema":{"type":"string","minLength":1,"maxLength":32,"default":"1.0.0"},"description":"Requested PPR version; currently only 1.0.0 is supported."}],"responses":{"200":{"description":"Portable Purchase Record 1.0.0","headers":{"PPR-Version":{"schema":{"const":"1.0.0"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortablePurchaseEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"406":{"description":"Requested PPR version is unsupported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnsupportedPprVersion"}}}},"422":{"description":"No safe monetary total is representable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-cases/{caseId}/objects":{"get":{"tags":["Commercial Cases"],"summary":"List safe case objects","security":[{"BearerAuth":["purchases:read"]},{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"$ref":"#/components/parameters/CommercialCaseId"}],"responses":{"200":{"description":"Safe objects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCaseObjectList"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-cases/{caseId}/assertions":{"get":{"tags":["Commercial Cases"],"summary":"List disclosure-safe case assertions","security":[{"BearerAuth":["purchases:read"]},{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"$ref":"#/components/parameters/CommercialCaseId"}],"responses":{"200":{"description":"Safe assertions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCaseAssertionList"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-cases/{caseId}/links":{"get":{"tags":["Commercial Cases"],"summary":"List case links","security":[{"BearerAuth":["purchases:read"]},{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"$ref":"#/components/parameters/CommercialCaseId"}],"responses":{"200":{"description":"Case links","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCaseLinkList"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-cases/{caseId}/allocations":{"get":{"tags":["Commercial Cases"],"summary":"List case allocations","security":[{"BearerAuth":["purchases:read"]},{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"$ref":"#/components/parameters/CommercialCaseId"}],"responses":{"200":{"description":"Case allocations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCaseAllocationList"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-cases/{caseId}/decisions":{"get":{"tags":["Commercial Cases"],"summary":"List case decisions","security":[{"BearerAuth":["purchases:read"]},{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"$ref":"#/components/parameters/CommercialCaseId"}],"responses":{"200":{"description":"Case decisions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCaseDecisionList"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"post":{"tags":["Commercial Cases"],"summary":"Append an auditable case decision","security":[{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"$ref":"#/components/parameters/CommercialCaseId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCaseDecisionRequest"},"examples":{"resolve":{"value":{"decision_type":"resolve","idempotency_key":"decision-2026-001","reason":"Verified against remittance."}}}}}},"responses":{"201":{"description":"Decision persisted"},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Link or allocation is no longer reviewable"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-cases/{caseId}/conflicts":{"get":{"tags":["Commercial Cases"],"summary":"List unresolved disclosure-safe conflicts","security":[{"BearerAuth":["purchases:read"]},{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"$ref":"#/components/parameters/CommercialCaseId"}],"responses":{"200":{"description":"Safe conflicts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCaseConflictList"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-cases/{caseId}/timeline":{"get":{"tags":["Commercial Cases"],"summary":"List the deterministic disclosure-safe timeline","security":[{"BearerAuth":["purchases:read"]},{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"$ref":"#/components/parameters/CommercialCaseId"}],"responses":{"200":{"description":"Safe timeline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCaseTimeline"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-cases/{caseId}/banking-ledger-context":{"get":{"tags":["Commercial Cases"],"summary":"Get safe banking ledger context","description":"Built only from available objects whose graph references are also available. Restricted, redacted, expired, and dangling object identifiers and hashes are omitted.","security":[{"BearerAuth":["purchases:read"]},{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"$ref":"#/components/parameters/CommercialCaseId"}],"responses":{"200":{"description":"Disclosure-safe banking context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCaseBankingContext"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases/{purchaseId}/project-commercial-case":{"post":{"tags":["Commercial Cases"],"summary":"Project a purchase into a Commercial Case","security":[{"BearerAuth":["purchases:write"]},{"BearerAuth":["compliance:write"]}],"parameters":[{"name":"purchaseId","in":"path","required":true,"schema":{"type":"string","maxLength":500}}],"responses":{"202":{"description":"Projection queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialCaseProjection"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/airwallex-delivery-configurations":{"post":{"tags":["Airwallex Deliveries"],"summary":"Create a credential-free Airwallex delivery configuration","description":"Requires `commercial-context:deliver`. Credentials are supplied only through server secrets, never this API.","security":[{"BearerAuth":["commercial-context:deliver"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirwallexDeliveryConfigurationCreate"}}}},"responses":{"201":{"description":"Configuration created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirwallexDeliveryConfiguration"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"409":{"description":"Provider account already configured"}},"x-viacle-exposure":"partner-only","x-viacle-audience":["approved-partner"],"x-viacle-authority-boundary":"Available only under an approved provider or institutional agreement."}},"/airwallex-delivery-configurations/{configurationId}":{"patch":{"tags":["Airwallex Deliveries"],"summary":"Update a credential-free Airwallex delivery configuration","description":"Requires `commercial-context:deliver`. Provider account identity and credentials are immutable through this API.","security":[{"BearerAuth":["commercial-context:deliver"]}],"parameters":[{"name":"configurationId","in":"path","required":true,"schema":{"type":"string","maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirwallexDeliveryConfigurationUpdate"}}}},"responses":{"200":{"description":"Configuration updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirwallexDeliveryConfiguration"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"partner-only","x-viacle-audience":["approved-partner"],"x-viacle-authority-boundary":"Available only under an approved provider or institutional agreement."}},"/airwallex-delivery-configurations/{configurationId}/validate":{"post":{"tags":["Airwallex Deliveries"],"summary":"Check Airwallex live-acceptance availability","description":"Requires `commercial-context:deliver`. Configurations remain unvalidated until account-bound live acceptance is completed; token acquisition alone never promotes delivery.","security":[{"BearerAuth":["commercial-context:deliver"]}],"parameters":[{"name":"configurationId","in":"path","required":true,"schema":{"type":"string","maxLength":100}}],"responses":{"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Account-bound live acceptance is required"},"503":{"description":"Delivery service schema is not ready"}},"x-viacle-exposure":"partner-only","x-viacle-audience":["approved-partner"],"x-viacle-authority-boundary":"Available only under an approved provider or institutional agreement."}},"/airwallex-deliveries":{"post":{"tags":["Airwallex Deliveries"],"summary":"Queue an Airwallex Commercial Case delivery","description":"Requires `commercial-context:deliver`. The immutable disclosure packet and its hash are derived by the server.","security":[{"BearerAuth":["commercial-context:deliver"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirwallexDeliveryRequest"},"examples":{"payment_intent":{"value":{"commercial_case_id":"ccase_123","configuration_id":"awc_123","idempotency_key":"delivery-001","target_type":"payment_intent","external_id":"pi_123"}}}}}},"responses":{"202":{"description":"Delivery queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirwallexDelivery"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Conflicting or duplicate delivery"}},"x-viacle-exposure":"partner-only","x-viacle-audience":["approved-partner"],"x-viacle-authority-boundary":"Available only under an approved provider or institutional agreement."}},"/airwallex-deliveries/{deliveryId}":{"get":{"tags":["Airwallex Deliveries"],"summary":"Get an Airwallex delivery","description":"Requires `commercial-context:deliver`.","security":[{"BearerAuth":["commercial-context:deliver"]}],"parameters":[{"$ref":"#/components/parameters/AirwallexDeliveryId"}],"responses":{"200":{"description":"Safe delivery status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirwallexDelivery"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"partner-only","x-viacle-audience":["approved-partner"],"x-viacle-authority-boundary":"Available only under an approved provider or institutional agreement."}},"/airwallex-deliveries/{deliveryId}/correct":{"post":{"tags":["Airwallex Deliveries"],"summary":"Queue a corrected Airwallex delivery","description":"Requires `commercial-context:deliver`.","security":[{"BearerAuth":["commercial-context:deliver"]}],"parameters":[{"$ref":"#/components/parameters/AirwallexDeliveryId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirwallexSuccessorRequest"}}}},"responses":{"202":{"description":"Correction queued"},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Cannot queue correction"}},"x-viacle-exposure":"partner-only","x-viacle-audience":["approved-partner"],"x-viacle-authority-boundary":"Available only under an approved provider or institutional agreement."}},"/airwallex-deliveries/{deliveryId}/revoke":{"post":{"tags":["Airwallex Deliveries"],"summary":"Queue an Airwallex delivery revocation","description":"Requires `commercial-context:deliver`.","security":[{"BearerAuth":["commercial-context:deliver"]}],"parameters":[{"$ref":"#/components/parameters/AirwallexDeliveryId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirwallexSuccessorRequest"}}}},"responses":{"202":{"description":"Revocation queued"},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Cannot queue revocation"}},"x-viacle-exposure":"partner-only","x-viacle-audience":["approved-partner"],"x-viacle-authority-boundary":"Available only under an approved provider or institutional agreement."}},"/commercial-events":{"post":{"operationId":"ingestCommercialEvent","tags":["Commercial Events"],"summary":"Create or incrementally enrich a Commercial Event","description":"Creates a persistent Commercial Event from one named, immutable source assertion. `source.connector_type` identifies the source system and `source.external_event_id` is its stable source record identity. Owners require `purchases:write`; a recipient attaching to `commercial_event_id` requires an active owner-issued `commercial_event:publish` grant. Provide `commercial_event_id` on later calls to attach new immutable source facts and evidence to the same event. Evidence is represented by the retained source signal; include its URI/reference, capture time, type, and digest in `source.metadata` when available. Omitted evidence remains absent, never inferred. Replaying the same connector/external-event pair with identical content is safe and returns the original event; a changed replay returns 409.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialEventIngest"}}}},"responses":{"200":{"description":"Idempotent replay; includes `Idempotency-Replayed: true`","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CommercialEvent"},{"$ref":"#/components/schemas/CommercialEventShared"}]}}}},"201":{"description":"Commercial Event created or enriched. Shared publishers receive only explicitly readable sections.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CommercialEvent"},{"$ref":"#/components/schemas/CommercialEventShared"}]}}}},"409":{"description":"A source identifier was replayed with different content or linked to a different event"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/exceptions/{id}/assignment":{"post":{"tags":["Commercial"],"summary":"Assign an AP exception","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["assignee"],"properties":{"assignee":{"type":["string","null"],"maxLength":200}}}}}},"responses":{"200":{"description":"Updated exception"},"404":{"description":"Not found"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/exceptions/{id}/due-date":{"post":{"tags":["Commercial"],"summary":"Set AP exception due date","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dueAt"],"properties":{"dueAt":{"type":["string","null"],"format":"date-time"}}}}}},"responses":{"200":{"description":"Updated exception"},"404":{"description":"Not found"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/exceptions/{id}/evidence-requests":{"post":{"tags":["Commercial"],"summary":"Queue a secure evidence request","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"description":"Queues durable outbox delivery. Receipt of a file never constitutes evidence acceptance or approval.","responses":{"201":{"description":"Request queued"},"404":{"description":"Not found"},"503":{"description":"Email delivery is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/exceptions":{"get":{"tags":["Commercial"],"summary":"List AP exception cases","description":"Returns safe exception projections only; workflow metadata, API-key IDs, and evidence delivery details are never returned.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"severity","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Exception list"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."},"post":{"tags":["Commercial"],"summary":"Create an AP exception case","security":[{"BearerAuth":["purchases:write"]}],"responses":{"201":{"description":"Exception case created"},"400":{"$ref":"#/components/responses/InvalidRequest"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/exceptions/{id}":{"get":{"tags":["Commercial"],"summary":"Get a safe AP exception case detail","description":"Events and evidence requests are allow-list projections and exclude metadata, recipient email, tokens, provider payloads, and raw delivery errors.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Exception detail"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/exceptions/{id}/decisions":{"post":{"tags":["Commercial"],"summary":"Record an exception decision","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated exception"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/exceptions/{id}/comments":{"post":{"tags":["Commercial"],"summary":"Add an internal exception comment","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated exception"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/exceptions/{id}/override":{"post":{"tags":["Commercial"],"summary":"Override an AP exception","description":"Unavailable until the dedicated `exceptions:override` API scope is provisioned. `purchases:write` never grants override authority.","security":[{"BearerAuth":["exceptions:override"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/exceptions/{id}/evidence":{"get":{"tags":["Commercial"],"summary":"Retrieve a redacted exception evidence bundle","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Redacted evidence bundle"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/exceptions/{id}/delivery-attempts":{"get":{"tags":["Commercial"],"summary":"List safe exception delivery attempt statuses","description":"Raw provider error messages and provider payloads are not returned.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Delivery attempt list"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/commercial-events/{id}":{"get":{"operationId":"getCommercialEvent","tags":["Commercial Events"],"summary":"Retrieve the canonical Commercial Event","description":"Owners require `purchases:read`. A recipient requires an active owner-issued `commercial_event:read` grant and receives only the grant's named sections. Missing, expired, revoked, under-scoped, or wrong-issuer grants return 404. The legacy Purchase Object remains available at the compatibility URL.","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Commercial Event ID (the stable public purchase ID)"}],"responses":{"200":{"description":"Owner event or section-filtered shared event","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CommercialEvent"},{"$ref":"#/components/schemas/CommercialEventShared"}]}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-events/{id}/relationships/{relationshipId}":{"post":{"operationId":"decideCommercialEventRelationship","tags":["Commercial Events"],"summary":"Confirm or reject a proposed relationship","description":"Records an explicit, auditable decision against a reviewable relationship and emits `commercial_event.relationship_updated` to configured webhooks.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"relationshipId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialEventRelationshipDecision"}}}},"responses":{"200":{"description":"Persisted relationship decision"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Relationship was already closed"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-events/{id}/relationships":{"post":{"operationId":"proposeCommercialEventRelationship","tags":["Commercial Events"],"summary":"Propose a reviewable payment relationship","description":"Records one `proposed` or `ambiguous` relationship for a named immutable payment observation; this operation never confirms a relationship. The same `source_type` and `source_id` with identical observation content safely returns the existing proposal with `Idempotency-Replayed: true`. Revised content supersedes only undecided proposals. A confirmed source relationship cannot be replaced.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Commercial Event / Purchase Object ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialEventRelationshipProposal"}}}},"responses":{"200":{"description":"Identical source observation replay","headers":{"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]}}}},"201":{"description":"Reviewable proposed or ambiguous relationship","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialEventRelationship"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Source relationship is already confirmed"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-events/{id}/actions":{"post":{"tags":["Commercial Events"],"summary":"Append an auditable Commercial Event action","description":"Owners require `purchases:write`; recipients require an active owner-issued `commercial_event:append` grant. Recipient idempotency and authenticated attribution are grant-scoped.","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialEventContextAppend"}}}},"responses":{"200":{"description":"Idempotent replay; includes Idempotency-Replayed: true"},"201":{"description":"Action appended"},"409":{"description":"Idempotency key replayed with changed payload"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-events/{id}/outcomes":{"post":{"tags":["Commercial Events"],"summary":"Append an auditable Commercial Event outcome","description":"Owners require `purchases:write`; recipients require an active owner-issued `commercial_event:append` grant. Recipient idempotency and authenticated attribution are grant-scoped.","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialEventContextAppend"}}}},"responses":{"200":{"description":"Idempotent replay; includes Idempotency-Replayed: true"},"201":{"description":"Outcome appended"},"409":{"description":"Idempotency key replayed with changed payload"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-events/{id}/reproject":{"post":{"tags":["Commercial Events"],"summary":"Rebuild the deterministic projection from stored evidence","description":"Recomputes the current projection from the tenant-scoped immutable evidence already attached to the Commercial Event. It does not create or rewrite source facts.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Reprojected Commercial Event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialEvent"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-events/{id}/shares":{"post":{"tags":["Commercial Events"],"summary":"Share one Commercial Event with another API key","description":"Owner-only. Creates an event-specific consent grant with explicit read, publish, or append operations plus section-level read permissions. The grant expires or can be revoked without transferring record ownership.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialEventShareRequest"}}}},"responses":{"201":{"description":"Commercial Event share created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialEventShare"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"get":{"tags":["Commercial Events"],"summary":"List active shares for one Commercial Event","description":"Owner-only. Returns grants for this exact Commercial Event resource. Expired grants are marked expired and never authorize access.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Commercial Event shares","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"resource":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/CommercialEventShare"}}}}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/commercial-events/{id}/shares/{grantId}":{"delete":{"tags":["Commercial Events"],"summary":"Revoke a Commercial Event share","description":"Owner-only. Revokes only a grant bound to this exact Commercial Event. Revocation takes effect before any later shared read, publish, or append.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"grantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Commercial Event share revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommercialEventShare"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/ingest/freight-load":{"post":{"tags":["Connectors"],"summary":"Ingest a freight load-close event and audit its invoice","description":"Accepts a load.closed, load.delivered, or pod.collected event from a freight operations platform. The event must include a carrier SCAC and contracted rate; invoice_amount is optional and produces pending_invoice until the carrier invoice arrives.","security":[{"BearerAuth":["freight:ingest"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event","contracted_rate","carrier"],"properties":{"event":{"type":"string","enum":["load.closed","load.delivered","pod.collected"]},"id":{"type":"string"},"load_id":{"type":"string"},"carrier":{"type":"object","required":["scac"],"properties":{"scac":{"type":"string","maxLength":10},"name":{"type":"string"}}},"contracted_rate":{"type":"number","exclusiveMinimum":0},"invoice_amount":{"type":"number","exclusiveMinimum":0},"delivery_confirmed_at":{"type":"string","format":"date-time"},"pod_reference":{"type":"string"}}}}}},"responses":{"200":{"description":"Inline freight invoice audit result","content":{"application/json":{"schema":{"type":"object","required":["status","delta_usd","dispute_ready"],"properties":{"status":{"type":"string","enum":["matched","overcharge","pending_invoice"]},"delta_usd":{"type":"number"},"dispute_ready":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases":{"get":{"tags":["Purchases"],"summary":"List purchases","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"starting_after","in":"query","schema":{"type":"string"},"description":"Cursor — public purchase ID to paginate after"},{"name":"entity_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","processing","completed","failed","reversed","refunded"]}},{"name":"signal_type","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Paginated list of purchase objects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"post":{"operationId":"createPurchase","tags":["Purchases"],"summary":"Create a purchase","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":255},"description":"Idempotency key for safe retries (24h TTL, scoped per API key)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePurchase"}}}},"responses":{"201":{"description":"Purchase created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases/batch":{"post":{"tags":["Purchases"],"summary":"Batch create up to 100 purchases","security":[{"BearerAuth":["purchases:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["purchases"],"properties":{"purchases":{"type":"array","items":{"$ref":"#/components/schemas/CreatePurchase"},"minItems":1,"maxItems":100}}}}}},"responses":{"207":{"description":"Multi-status — inspect each result individually","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"status":{"type":"integer"},"body":{"type":"object"}}}}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases/{id}":{"get":{"tags":["Purchases"],"summary":"Get a purchase","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"responses":{"200":{"description":"Purchase object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"patch":{"tags":["Purchases"],"summary":"Update a purchase","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"merchant_name":{"type":"string","maxLength":200},"status":{"type":"string","enum":["pending","processing","completed","failed","reversed","refunded"]},"memo":{"type":"string","nullable":true},"tax":{"type":"number","nullable":true},"total":{"type":"number","nullable":true},"gl_code":{"type":"string","maxLength":50,"nullable":true},"cost_center":{"type":"string","maxLength":100,"nullable":true},"department":{"type":"string","maxLength":100,"nullable":true},"project_code":{"type":"string","maxLength":100,"nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}}}}}}},"responses":{"200":{"description":"Updated purchase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"delete":{"tags":["Purchases"],"summary":"Delete a purchase","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"id":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases/{id}/approve":{"post":{"tags":["Purchases"],"summary":"Approve an expense purchase","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"approved_by":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"Approved purchase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases/{id}/reject":{"post":{"tags":["Purchases"],"summary":"Reject an expense purchase","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rejection_reason"],"properties":{"rejection_reason":{"type":"string","minLength":1,"maxLength":1000}}}}}},"responses":{"200":{"description":"Rejected purchase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases/{id}/reimburse":{"post":{"tags":["Purchases"],"summary":"Mark an approved expense as reimbursed","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"responses":{"200":{"description":"Reimbursed purchase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Purchase is not in approved state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases/{id}/unify":{"post":{"tags":["Purchases"],"summary":"Trigger merchant unification for a purchase","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"responses":{"200":{"description":"Unification result"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases/{id}/events":{"get":{"tags":["Purchases"],"summary":"List events on a purchase","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"responses":{"200":{"description":"Event list"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"post":{"tags":["Purchases"],"summary":"Append a custom event to a purchase","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event_type"],"properties":{"event_type":{"type":"string"},"data":{"type":"object"}}}}}},"responses":{"201":{"description":"Event created"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases/{id}/lifecycle":{"get":{"operationId":"listPurchaseLifecycleEvents","tags":["Purchases"],"summary":"List post-delivery lifecycle events","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"},{"name":"event_type","in":"query","schema":{"type":"string","enum":["warranty_activated","warranty_expired","return_window_opened","return_window_closed","subscription_renewal","asset_depreciation_posted","audit_referenced","payment_dispute_opened","payment_dispute_resolved","asset_received"]}}],"responses":{"200":{"description":"Timestamp-ordered lifecycle events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostDeliveryLifecycleEventList"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"post":{"operationId":"appendPurchaseLifecycleEvent","tags":["Purchases"],"summary":"Append a post-delivery lifecycle event","description":"Appends an immutable lifecycle assertion. Supply a stable `idempotency_key` for retry safety: an identical replay returns the original event with `Idempotency-Replayed: true`; a changed payload using that key returns 409 `LIFECYCLE_IDEMPOTENCY_MISMATCH`. This is the lifecycle route; `/events` is not a public lifecycle endpoint.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePostDeliveryLifecycleEvent"}}}},"responses":{"201":{"description":"Lifecycle event created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostDeliveryLifecycleEvent"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Idempotency key replayed with a changed lifecycle payload"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases/{id}/provenance":{"get":{"operationId":"getPurchaseProvenance","tags":["Purchases"],"summary":"Retrieve field-level Purchase Object provenance","description":"Returns the current field values with their stored derivation class, named source summary, observation time, and available confidence. A field with no supporting assertion is explicitly reported as `absent`; evidence is never fabricated.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"responses":{"200":{"description":"Field provenance for the current Purchase Object"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases/{id}/corrections":{"get":{"operationId":"listPurchaseCorrections","tags":["Purchases"],"summary":"List immutable Purchase Object corrections","description":"Lists append-only corrections to this Purchase Object. Source-aware corrections are created through the normal Purchase Object ingest request's `source_correction` metadata, preserving the original purchase/source reference and effective time without rewriting history.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"responses":{"200":{"description":"Correction chain"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"post":{"operationId":"createPurchaseCorrection","tags":["Purchases"],"summary":"Append an immutable field correction","description":"Appends a correction; it does not overwrite the original assertion. For a correction with source reference, effective time, reason, and amount delta, use the existing `source_correction` object when creating the correction Purchase Object.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"responses":{"201":{"description":"Correction appended"},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/entities":{"get":{"tags":["Entities"],"summary":"List entities","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"starting_after","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Entity list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityList"}}}}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"post":{"tags":["Entities"],"summary":"Create or merge an entity","security":[{"BearerAuth":["purchases:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEntity"}}}},"responses":{"201":{"description":"Entity created or merged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"}}}}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/entities/{entityId}":{"get":{"tags":["Entities"],"summary":"Get an entity","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"$ref":"#/components/parameters/EntityId"}],"responses":{"200":{"description":"Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"patch":{"tags":["Entities"],"summary":"Update an entity","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/EntityId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEntity"}}}},"responses":{"200":{"description":"Updated entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"}}}}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/entities/{entityId}/purchases":{"get":{"tags":["Entities"],"summary":"List purchases for an entity","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"$ref":"#/components/parameters/EntityId"},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Purchase list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseList"}}}}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/entities/{entityId}/ownership":{"get":{"tags":["Entities","Ownership"],"summary":"Ownership records for an entity","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/EntityId"}],"responses":{"200":{"description":"Ownership list"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/entities/{entityId}/intelligence/summary":{"get":{"tags":["Intelligence","Entities"],"summary":"Entity intelligence summary","description":"Aggregates intelligence signals across all purchases for an entity: active warranty count, warranties expiring this calendar month, flagged duplicate count, total depreciated asset value, and recall-flagged purchase count. Accepts both internal Viacle entity IDs and caller-provided external IDs. Requires `purchases:read`.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"$ref":"#/components/parameters/EntityId"}],"responses":{"200":{"description":"Entity intelligence summary","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"entity_intelligence_summary"},"entity_id":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"total_active_warranties":{"type":"integer"},"warranties_expiring_this_month":{"type":"integer"},"total_flagged_duplicates":{"type":"integer"},"total_depreciated_asset_value":{"type":"number","description":"Sum of purchase amounts for receipts over $500 (proxy for depreciable assets). Use GET /entities/:id/depreciation-schedule for per-asset straight-line schedules."},"recall_flagged_purchases":{"type":"integer","description":"Count of purchases with active recall flags. 0 in current release — recall detection is per-request and not yet persisted."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"experimental","x-viacle-audience":["evaluation-only"],"x-viacle-authority-boundary":"Semantics and support commitment are not generally available."}},"/entities/{entityId}/summary":{"get":{"tags":["Entities"],"summary":"Spend summary for an entity","security":[{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/EntityId"}],"responses":{"200":{"description":"Summary"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/entities/{entityId}/tax-summary":{"get":{"tags":["Tax","Entities"],"summary":"TIN-scoped vendor totals by tax year","security":[{"BearerAuth":["tax:read"]}],"parameters":[{"$ref":"#/components/parameters/EntityId"},{"name":"year","in":"query","required":true,"schema":{"type":"integer","example":2025}}],"responses":{"200":{"description":"Tax summary with 1099-reportability flags"}},"x-viacle-exposure":"vertical-adapter","x-viacle-audience":["institutional-distributor","domain-system"],"x-viacle-authority-boundary":"Preserves or delivers domain evidence without operating the adjacent domain workflow."}},"/entities/{entityId}/recurring-merchants":{"get":{"tags":["Tax","Entities"],"summary":"Detect recurring merchant spending patterns","security":[{"BearerAuth":["tax:read"]}],"parameters":[{"$ref":"#/components/parameters/EntityId"}],"responses":{"200":{"description":"Recurring merchant list with confidence and next-expected-date"}},"x-viacle-exposure":"vertical-adapter","x-viacle-audience":["institutional-distributor","domain-system"],"x-viacle-authority-boundary":"Preserves or delivers domain evidence without operating the adjacent domain workflow."}},"/entities/{entityId}/insurance-claim-summary":{"get":{"tags":["Insurance","Entities"],"summary":"Insurance claim summary for an entity","description":"Aggregates all purchases with `insurance_claim_metadata` for the entity. Returns total claims, total payout, breakdowns by claim type and status, and counts of proceeds receipts. Requires `tax:read` scope.","security":[{"BearerAuth":["tax:read"]}],"parameters":[{"$ref":"#/components/parameters/EntityId"}],"responses":{"200":{"description":"Insurance claim summary","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"insurance_claim_summary"},"entity_id":{"type":"string"},"total_claims":{"type":"integer"},"total_payout":{"type":"number"},"by_claim_type":{"type":"array","items":{"type":"object","properties":{"claim_type":{"type":"string"},"count":{"type":"integer"},"total_payout":{"type":"number"},"currency":{"type":"string"}}}},"by_status":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"count":{"type":"integer"}}}},"receipts_with_claim_metadata":{"type":"integer"},"receipts_preserved_for_insurance":{"type":"integer"},"generated_at":{"type":"integer","description":"Unix timestamp"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"vertical-adapter","x-viacle-audience":["institutional-distributor","domain-system"],"x-viacle-authority-boundary":"Preserves or delivers domain evidence without operating the adjacent domain workflow."}},"/purchases/{id}/insurance-claim":{"patch":{"tags":["Insurance","Purchases"],"summary":"Attach or update insurance claim metadata","description":"Attaches structured insurance claim data to a purchase. Returns a claim-readiness score (0–1, graded excellent/good/fair/poor), per-signal breakdown, and recommendations. When `payout_amount` is present, US federal insurance proceeds taxability is classified inline (IRC §§ 101, 105, 1001, 1033).","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["claim_type"],"properties":{"claim_type":{"type":"string","enum":["property_damage","theft","loss","liability","travel","auto","health","life","renters","homeowners","business_interruption","other"],"example":"renters"},"insurer_name":{"type":"string","example":"Lemonade"},"policy_number":{"type":"string","example":"LEM-2026-001"},"claim_number":{"type":"string","example":"CLM-00999"},"claim_status":{"type":"string","enum":["pending","submitted","under_review","approved","partially_approved","denied","appealed","settled","withdrawn"]},"date_of_loss":{"type":"string","format":"date","example":"2026-04-12"},"date_filed":{"type":"string","format":"date"},"date_settled":{"type":"string","format":"date"},"payout_amount":{"type":"number","description":"Claim payout amount. Triggers inline proceeds tax classification.","example":1250},"payout_currency":{"type":"string","example":"USD"},"deductible_applied":{"type":"number","example":250},"replacement_cost_value":{"type":"boolean"},"actual_cash_value":{"type":"number"},"depreciation_withheld":{"type":"number"},"is_proceeds_receipt":{"type":"boolean","description":"True when this purchase IS the insurance payout receipt."},"notes":{"type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"Claim metadata attached, readiness score computed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"vertical-adapter","x-viacle-audience":["institutional-distributor","domain-system"],"x-viacle-authority-boundary":"Preserves or delivers domain evidence without operating the adjacent domain workflow."},"get":{"tags":["Insurance","Purchases"],"summary":"Get insurance claim metadata and readiness score","description":"Returns the current `insurance_claim_metadata`, claim-readiness score, and proceeds tax intelligence for a purchase, without writing.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"responses":{"200":{"description":"Insurance claim data and readiness score"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"vertical-adapter","x-viacle-audience":["institutional-distributor","domain-system"],"x-viacle-authority-boundary":"Preserves or delivers domain evidence without operating the adjacent domain workflow."}},"/purchases/{id}/binding-receipt":{"patch":{"tags":["Insurance","Purchases"],"summary":"Attach binding receipt metadata","description":"Marks a purchase as a binding receipt — the temporary coverage document issued by an insurer at policy inception. Supports `conditional`, `unconditional`, and `temporary` binder types. Returns `binding_status` (bound / conditionally_bound / pending_underwriting) and a real-time `coverage_active` boolean derived from effective/expiry dates.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["receipt_type"],"properties":{"receipt_type":{"type":"string","enum":["conditional","unconditional","temporary"],"example":"conditional"},"policy_type":{"type":"string","example":"renters"},"insurer_name":{"type":"string","example":"Lemonade"},"policy_number":{"type":"string"},"effective_date":{"type":"string","format":"date","example":"2026-06-01"},"expiry_date":{"type":"string","format":"date","example":"2026-07-01"},"coverage_amount":{"type":"number","example":50000},"coverage_currency":{"type":"string","example":"USD"},"premium_paid":{"type":"number","example":14.99},"conditions":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Conditions attached to a conditional binder."},"applicant_name":{"type":"string"},"underwriting_pending":{"type":"boolean"},"bound_by":{"type":"string","description":"Name of agent or underwriter."}}}}}},"responses":{"200":{"description":"Binding receipt metadata attached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"vertical-adapter","x-viacle-audience":["institutional-distributor","domain-system"],"x-viacle-authority-boundary":"Preserves or delivers domain evidence without operating the adjacent domain workflow."}},"/purchases/{id}/insurance-proceeds-tax":{"post":{"tags":["Insurance","Tax"],"summary":"Classify insurance proceeds taxability","description":"On-demand US federal tax classification for a purchase's insurance payout. Requires `insurance_claim_metadata` with `payout_amount` already attached. Applies IRC §§ 101 (life), 105 (health), 1001 (basis), and 1033 (involuntary conversion) rules by claim type. Pass `is_business_property: true` for business asset claims (affects §§ 1231/1245 analysis). Results are informational — consult a qualified tax professional.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"is_business_property":{"type":"boolean","default":false,"description":"Set true for business-owned assets."},"original_purchase_amount":{"type":"number","description":"Override the purchase amount used as cost basis."}}}}}},"responses":{"200":{"description":"Tax classification result","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"insurance_proceeds_tax"},"is_taxable_proceeds":{"type":"boolean"},"taxability":{"type":"string","enum":["non_taxable","partially_taxable","taxable","requires_review"]},"taxable_gain_estimate":{"type":"number","nullable":true},"basis":{"type":"number","nullable":true},"rationale":{"type":"string"},"irs_reference":{"type":"string"},"requires_professional_review":{"type":"boolean"},"disclaimer":{"type":"string"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"No insurance_claim_metadata or payout_amount present"}},"x-viacle-exposure":"vertical-adapter","x-viacle-audience":["institutional-distributor","domain-system"],"x-viacle-authority-boundary":"Preserves or delivers domain evidence without operating the adjacent domain workflow."}},"/entities/{entityId}/kyc":{"patch":{"tags":["Entities"],"summary":"Update KYC status for an entity","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/EntityId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kyc_status"],"properties":{"kyc_status":{"type":"string","enum":["pending","verified","failed","expired"]}}}}}},"responses":{"200":{"description":"Updated entity"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/expenses/mileage":{"post":{"tags":["Expenses"],"summary":"Record a mileage reimbursement expense","description":"Creates a purchase object at the IRS 2026 rate ($0.70/mile) with `pending_review` approval status.","security":[{"BearerAuth":["expenses:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date","miles","purpose"],"properties":{"entity_id":{"type":"string"},"date":{"type":"string","format":"date","example":"2025-04-15"},"miles":{"type":"number","exclusiveMinimum":0},"rate_per_mile":{"type":"number","description":"Defaults to $0.70 (IRS 2026)"},"purpose":{"type":"string","maxLength":500},"gl_code":{"type":"string","maxLength":50},"cost_center":{"type":"string","maxLength":100},"department":{"type":"string","maxLength":100},"project_code":{"type":"string","maxLength":100},"memo":{"type":"string","maxLength":1000}}}}}},"responses":{"201":{"description":"Mileage purchase object","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Purchase"},{"type":"object","properties":{"expense_type":{"type":"string","enum":["mileage"]},"mileage":{"type":"object","properties":{"miles":{"type":"number"},"rate_per_mile":{"type":"number"},"purpose":{"type":"string"}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidRequest"}},"x-viacle-exposure":"experimental","x-viacle-audience":["evaluation-only"],"x-viacle-authority-boundary":"Semantics and support commitment are not generally available."}},"/expenses/per-diem":{"post":{"tags":["Expenses"],"summary":"Record a per-diem travel expense","security":[{"BearerAuth":["expenses:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["start_date","days","rate_per_day","location","purpose"],"properties":{"entity_id":{"type":"string"},"start_date":{"type":"string","format":"date"},"days":{"type":"integer","minimum":1},"rate_per_day":{"type":"number","exclusiveMinimum":0},"location":{"type":"string","maxLength":200},"purpose":{"type":"string","maxLength":500},"gl_code":{"type":"string","maxLength":50},"cost_center":{"type":"string","maxLength":100},"department":{"type":"string","maxLength":100},"project_code":{"type":"string","maxLength":100},"memo":{"type":"string","maxLength":1000}}}}}},"responses":{"201":{"description":"Per-diem purchase object","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Purchase"},{"type":"object","properties":{"expense_type":{"type":"string","enum":["per_diem"]},"per_diem":{"type":"object"}}}]}}}},"400":{"$ref":"#/components/responses/InvalidRequest"}},"x-viacle-exposure":"experimental","x-viacle-audience":["evaluation-only"],"x-viacle-authority-boundary":"Semantics and support commitment are not generally available."}},"/policies":{"get":{"tags":["Policies"],"summary":"List expense policies","security":[{"BearerAuth":["policies:read"]}],"responses":{"200":{"description":"Policy list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}}}}}}}},"x-viacle-exposure":"experimental","x-viacle-audience":["evaluation-only"],"x-viacle-authority-boundary":"Semantics and support commitment are not generally available."},"post":{"tags":["Policies"],"summary":"Create an expense policy","security":[{"BearerAuth":["policies:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePolicy"}}}},"responses":{"201":{"description":"Created policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}}},"x-viacle-exposure":"experimental","x-viacle-audience":["evaluation-only"],"x-viacle-authority-boundary":"Semantics and support commitment are not generally available."}},"/policies/{id}":{"get":{"tags":["Policies"],"summary":"Get a policy","security":[{"BearerAuth":["policies:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"experimental","x-viacle-audience":["evaluation-only"],"x-viacle-authority-boundary":"Semantics and support commitment are not generally available."},"put":{"tags":["Policies"],"summary":"Update a policy","security":[{"BearerAuth":["policies:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePolicy"}}}},"responses":{"200":{"description":"Updated policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}}},"x-viacle-exposure":"experimental","x-viacle-audience":["evaluation-only"],"x-viacle-authority-boundary":"Semantics and support commitment are not generally available."},"delete":{"tags":["Policies"],"summary":"Delete a policy","security":[{"BearerAuth":["policies:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}},"x-viacle-exposure":"experimental","x-viacle-audience":["evaluation-only"],"x-viacle-authority-boundary":"Semantics and support commitment are not generally available."}},"/webhooks/endpoints":{"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","security":[{"BearerAuth":["purchases:read"]}],"responses":{"200":{"description":"Webhook endpoint list"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"post":{"operationId":"createWebhookEndpoint","tags":["Webhooks"],"summary":"Create a webhook endpoint","description":"Returns a signing secret only in this creation response. Viacle signs the exact raw JSON body with HMAC-SHA256 base64 and sends it in `X-Viacle-Signature`; verify with a constant-time comparison. Deliveries include `X-Viacle-Event`, `X-Viacle-Delivery`, and `X-Viacle-Attempt`. A non-2xx response or timeout is retried up to three attempts; delivery logs expose each attempt.","security":[{"BearerAuth":["purchases:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","url","events"],"properties":{"name":{"type":"string","maxLength":100},"url":{"type":"string","format":"uri","maxLength":500},"events":{"type":"array","items":{"type":"string"},"description":"e.g. [\"purchase.created\", \"merchant.enriched\"]"}}}}}},"responses":{"201":{"description":"Created endpoint"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/webhooks/endpoints/{id}":{"get":{"tags":["Webhooks"],"summary":"Get a webhook endpoint","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Endpoint"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"put":{"tags":["Webhooks"],"summary":"Update a webhook endpoint","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook endpoint","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/webhooks/endpoints/{id}/enable":{"post":{"tags":["Webhooks"],"summary":"Enable a webhook endpoint","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Enabled"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/webhooks/endpoints/{id}/disable":{"post":{"tags":["Webhooks"],"summary":"Disable a webhook endpoint","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Disabled"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/webhooks/endpoints/{id}/test":{"post":{"tags":["Webhooks"],"summary":"Send a test event to a webhook endpoint","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Test dispatched"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/webhooks/endpoints/{id}/events":{"get":{"tags":["Webhooks"],"summary":"List events for a webhook endpoint","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Event list"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/webhooks/endpoints/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"List delivery attempts for a webhook endpoint","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Delivery list"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/webhook-events":{"get":{"tags":["Webhooks"],"summary":"List all webhook events (event log)","security":[{"BearerAuth":["purchases:read"]}],"responses":{"200":{"description":"Event log"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/available":{"get":{"tags":["Connectors"],"summary":"List all available connector types (no auth)","responses":{"200":{"description":"Available connectors"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors":{"get":{"tags":["Connectors"],"summary":"List configured connectors","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Connector list"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"post":{"tags":["Connectors"],"summary":"Create a connector","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["connector_type","credentials"],"properties":{"connector_type":{"type":"string"},"credentials":{"type":"object"},"name":{"type":"string"},"sync_enabled":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Created connector"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/{id}":{"get":{"tags":["Connectors"],"summary":"Get a connector","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Connector"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"patch":{"tags":["Connectors"],"summary":"Update a connector","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"delete":{"tags":["Connectors"],"summary":"Delete a connector","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/{id}/test":{"post":{"tags":["Connectors"],"summary":"Test connector credentials","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Test result"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/{id}/sync":{"post":{"tags":["Connectors"],"summary":"Trigger a manual sync","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sync result"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/{id}/logs":{"get":{"tags":["Connectors"],"summary":"Get sync logs for a connector","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sync logs"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/graph/merchants":{"get":{"tags":["Merchants"],"summary":"List merchants in the global purchase graph","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Merchant list"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/graph/merchants/{id}":{"get":{"tags":["Merchants"],"summary":"Get a merchant","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Merchant"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/graph/products":{"get":{"tags":["Products"],"summary":"List products in the global purchase graph","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Product list"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/graph/products/{id}":{"get":{"tags":["Products"],"summary":"Get a product","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Product"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/ownership":{"get":{"tags":["Ownership"],"summary":"List ownership records","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Ownership list"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/ownership/{id}":{"get":{"tags":["Ownership"],"summary":"Get an ownership record","security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ownership record"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/fdx/consents":{"get":{"tags":["FDX"],"summary":"List FDX consents","security":[{"BearerAuth":["fdx:read"]}],"responses":{"200":{"description":"Consent list"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."},"post":{"tags":["FDX"],"summary":"Create an FDX consent","security":[{"BearerAuth":["fdx:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Consent created"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/fdx/consents/{consentId}":{"get":{"tags":["FDX"],"summary":"Get an FDX consent","security":[{"BearerAuth":["fdx:read"]}],"parameters":[{"name":"consentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Consent"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."},"delete":{"tags":["FDX"],"summary":"Revoke an FDX consent","security":[{"BearerAuth":["fdx:write"]}],"parameters":[{"name":"consentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/fdx/accounts":{"get":{"tags":["FDX"],"summary":"List FDX accounts","security":[{"BearerAuth":["fdx:read"]}],"responses":{"200":{"description":"Account list"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."},"post":{"tags":["FDX"],"summary":"Register an FDX account","security":[{"BearerAuth":["fdx:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Account created"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/fdx/accounts/{accountId}/transactions":{"get":{"tags":["FDX"],"summary":"List transactions for an FDX account","security":[{"BearerAuth":["fdx:read"]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Transaction list"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."},"post":{"tags":["FDX"],"summary":"Ingest a transaction for an FDX account","security":[{"BearerAuth":["fdx:write"]}],"parameters":[{"name":"accountId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Transaction ingested"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/fdx/transactions/{transactionId}":{"get":{"tags":["FDX"],"summary":"Get an FDX transaction","security":[{"BearerAuth":["fdx:read"]}],"parameters":[{"name":"transactionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Transaction"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/fdx/transactions/{transactionId}/pair":{"post":{"tags":["FDX"],"summary":"Pair an FDX transaction to a purchase","security":[{"BearerAuth":["fdx:write"]}],"parameters":[{"name":"transactionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["purchase_id"],"properties":{"purchase_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Paired"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."},"delete":{"tags":["FDX"],"summary":"Unpair an FDX transaction from a purchase","security":[{"BearerAuth":["fdx:write"]}],"parameters":[{"name":"transactionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Unpaired"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/fdx/tax-statements":{"get":{"tags":["FDX"],"summary":"List FDX tax statements","security":[{"BearerAuth":["fdx:read"]}],"responses":{"200":{"description":"Tax statement list"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."},"post":{"tags":["FDX"],"summary":"Create an FDX tax statement","security":[{"BearerAuth":["fdx:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Statement created"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/purchases/{id}/compliance":{"get":{"tags":["Compliance"],"summary":"List compliance events for a purchase","security":[{"BearerAuth":["compliance:read"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"responses":{"200":{"description":"Compliance event list"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."},"post":{"tags":["Compliance"],"summary":"Append a compliance event to a purchase","security":[{"BearerAuth":["compliance:write"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event_type","severity"],"properties":{"event_type":{"type":"string"},"severity":{"type":"string","enum":["low","medium","high"]},"note":{"type":"string"},"entity_id":{"type":"string"}}}}}},"responses":{"201":{"description":"Compliance event created"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/compliance/export":{"get":{"tags":["Compliance"],"summary":"Export compliance events (NDJSON or CSV)","description":"Returns up to `limit` events (default 1000, max 10000). Use `from`/`to` date filters and `starting_after` for pagination over large datasets.","security":[{"BearerAuth":["compliance:read"]}],"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"format","in":"query","schema":{"type":"string","enum":["ndjson","csv"],"default":"ndjson"}},{"name":"limit","in":"query","schema":{"type":"integer","default":1000,"maximum":10000}}],"responses":{"200":{"description":"Compliance export","content":{"application/x-ndjson":{"schema":{"type":"string"}},"text/csv":{"schema":{"type":"string"}}}}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/purchases/ingest":{"post":{"tags":["Commercial","Purchases"],"summary":"AP invoice ingest — structured invoice → purchase object + commercial block","description":"AP-workflow-focused alternative to POST /purchases. Accepts vendor name, line items, PO reference, and payment terms. Returns the full normalized purchase object with the `commercial` block and an `ingest_summary` envelope containing the key AP decision signals: `auto_codeable`, `recommended_action`, `gl_code`, `po_matched`, and `reportable_1099`. See the interactive demo at /demo/ap-flow.","security":[{"BearerAuth":["purchases:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["vendor_name","amount"],"properties":{"vendor_name":{"type":"string","description":"Vendor / supplier display name","example":"Salesforce"},"amount":{"type":"number","description":"Invoice total","example":24000},"currency":{"type":"string","description":"ISO 4217 (default: USD)","default":"USD"},"line_items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"number","default":1},"commodity_code":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true}}}},"po_reference":{"type":"string","description":"PO number or AP reference. Used for po_match in the commercial block.","example":"AP-SAAS-2026-0198"},"invoice_number":{"type":"string","nullable":true},"invoice_date":{"type":"string","format":"date","example":"2026-07-27"},"payment_terms":{"type":"string","example":"Net 30"},"vendor_tin":{"type":"string","description":"Vendor EIN/TIN — written to merchant record, used for 1099 aggregation.","example":"94-1107761"},"cost_center":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"project_code":{"type":"string","nullable":true},"entity_id":{"type":"string","nullable":true},"memo":{"type":"string","nullable":true}}}}}},"responses":{"201":{"description":"Normalized purchase object with commercial block and ingest_summary","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Purchase"},{"type":"object","properties":{"ingest_summary":{"type":"object","properties":{"auto_codeable":{"type":"boolean"},"gl_code":{"type":"string","nullable":true},"gl_description":{"type":"string","nullable":true},"po_matched":{"type":"boolean"},"exception_count":{"type":"integer"},"error_exception_count":{"type":"integer"},"reportable_1099":{"type":"boolean","nullable":true},"recommended_action":{"type":"string","enum":["auto_post","review_recommended","hold_for_review"]}}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/purchases/match":{"post":{"tags":["Matching"],"summary":"Match a transaction signal to existing purchases","description":"Scores an incoming transaction (amount, merchant, date, optional reference ID) against existing purchase records and returns the best match with a confidence score, `match_status`, and the exact evidence signals that drove the link. Scores ≥ 85 auto-link, 70–84 are returned as suggestions, below 70 is `no_match`. Requires `purchases:read`.","security":[{"BearerAuth":["purchases:read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","merchant_name","date"],"properties":{"amount":{"type":"number","example":2487.6},"currency":{"type":"string","default":"USD"},"merchant_name":{"type":"string","example":"W.W. Grainger"},"date":{"type":"string","description":"YYYY-MM-DD","example":"2026-03-14"},"reference_id":{"type":"string","nullable":true},"entity_id":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Best match plus up to 5 scored candidates, each carrying the evidence signals used","content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["auto_linked","suggested","no_match"]},"match":{"type":"object","nullable":true,"properties":{"purchase_id":{"type":"string","example":"pur_vc_4fa82e19c30b47d2a1f8e6c25b9d0341"},"confidence":{"type":"number","example":95},"match_status":{"type":"string","enum":["exact_match","high_confidence","suggested"]},"signals":{"type":"array","items":{"type":"string"},"example":["amount","merchant","date","reference_id"]},"merchant":{"type":"string","nullable":true},"amount":{"type":"number"},"date":{"type":"string"}}},"candidates":{"type":"array","maxItems":5,"items":{"type":"object","properties":{"purchase_id":{"type":"string"},"confidence":{"type":"number"},"match_status":{"type":"string","enum":["exact_match","high_confidence","suggested"]},"signals":{"type":"array","items":{"type":"string"}}}}}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/purchases/match/feedback":{"post":{"tags":["Matching"],"summary":"Record human feedback on a suggested match","description":"Confirms or rejects a previously suggested match. Confirmations formally link the two purchase records; both outcomes are written to the event log so matching improves over time. Requires `purchases:write`.","security":[{"BearerAuth":["purchases:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["purchase_id","candidate_purchase_id","outcome"],"properties":{"purchase_id":{"type":"string"},"candidate_purchase_id":{"type":"string"},"outcome":{"type":"string","enum":["confirmed","rejected"]},"note":{"type":"string","nullable":true,"maxLength":500}}}}}},"responses":{"200":{"description":"Feedback recorded (and records linked when confirmed)"},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"One or both purchase IDs not found"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/payments/allocation-candidates":{"post":{"tags":["Matching","Payments"],"summary":"Decompose a payment into the invoices it settles","description":"Given a single payment (e.g. one ACH transfer or wire), finds the combination of open invoices that the payment most plausibly settles — including many-to-one cases where one payment covers several invoices. Returns proposed allocations with per-invoice amounts and confidence. Read-only; nothing is persisted until you call `/payments/allocate`. Requires `purchases:read`.","security":[{"BearerAuth":["purchases:read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payment_id"],"properties":{"payment_id":{"type":"string","description":"Purchase ID of the payment-side record","example":"pur_vc_9a11f4c2d8e34b6f90a2c5d7e8f10234"},"max_days_diff":{"type":"integer","default":60,"description":"Maximum age gap in days between payment and candidate invoices"}}}}}},"responses":{"200":{"description":"Proposed invoice allocations for the payment","content":{"application/json":{"schema":{"type":"object","properties":{"payment_id":{"type":"string"},"candidates":{"type":"array","items":{"type":"object","properties":{"invoice_id":{"type":"string","example":"pur_vc_c4d92e01ab34f5678d90e1f2a3b45c67"},"allocated_amount":{"type":"number","example":1250},"confidence":{"type":"number","example":91},"status":{"type":"string","example":"proposed"}}}}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Payment not found"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/payments/allocate":{"post":{"tags":["Matching","Payments"],"summary":"Persist payment-to-invoice allocations","description":"Confirms and persists a set of payment-to-invoice allocations (bulk). Every invoice is ownership-checked before anything is written. Requires `purchases:write`.","security":[{"BearerAuth":["purchases:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payment_id","allocations"],"properties":{"payment_id":{"type":"string"},"allocations":{"type":"array","maxItems":100,"items":{"type":"object","required":["invoice_id","allocated_amount"],"properties":{"invoice_id":{"type":"string"},"allocated_amount":{"type":"number"},"confidence":{"type":"number"}}}}}}}}},"responses":{"200":{"description":"Allocations persisted with status `confirmed`"},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Payment or invoice not found"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/payments/allocations/{id}/confirm":{"post":{"tags":["Matching","Payments"],"summary":"Confirm a proposed allocation","description":"Confirms a single previously proposed payment-to-invoice allocation. Requires `purchases:write`.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Allocation ID (`palloc_...`)"}],"responses":{"200":{"description":"Allocation confirmed"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Allocation not found"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/purchases/{id}/link":{"post":{"tags":["Matching","Purchases"],"summary":"Manually link an external transaction reference","description":"Links an external transaction reference (e.g. a card transaction ID) to an existing purchase record. Idempotent on `reference_id`. Requires `purchases:write`.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reference_id"],"properties":{"reference_id":{"type":"string"},"signal_type":{"type":"string","enum":["card_transaction","receipt","invoice","email_confirmation","api_submission","mobile_capture","wallet_payment"],"default":"card_transaction"},"amount":{"type":"number","nullable":true},"note":{"type":"string","nullable":true,"maxLength":500}}}}}},"responses":{"200":{"description":"Reference linked to the purchase"},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Purchase not found"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/purchases/{id}/intelligence":{"get":{"tags":["Intelligence","Purchases"],"summary":"Get purchase intelligence signals","description":"Returns the full `purchase_intelligence` object for a purchase: recall detection (CPSC/FDA/NHTSA), subscription detection, warranty status, depreciation status, vendor risk, GL recommendation, tax treatment recommendation (with disclaimer), duplicate probability, and up to 10 related purchases. Requires `purchases:read`.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"responses":{"200":{"description":"Purchase intelligence object","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"purchase_intelligence"},"purchase_id":{"type":"string","example":"pur_vc_abc123"},"generated_at":{"type":"string","format":"date-time"},"merchant_confidence":{"type":"number","minimum":0,"maximum":1},"category":{"type":"string","nullable":true,"example":"software_subscription"},"likely_business_expense":{"type":"boolean","nullable":true},"ownership_verified":{"type":"boolean"},"vendor_risk":{"type":"string","enum":["low","medium","high"]},"warranty_status":{"nullable":true,"type":"object","properties":{"active":{"type":"boolean"},"expiry_date":{"type":"string","format":"date"},"days_remaining":{"type":"integer"}}},"depreciation_status":{"nullable":true,"type":"object","properties":{"asset_class":{"type":"string"},"useful_life_years":{"type":"number"},"purchase_date":{"type":"string","format":"date"},"current_book_value":{"type":"number"},"fully_depreciated":{"type":"boolean"}}},"duplicate_purchase_probability":{"type":"number","nullable":true,"minimum":0,"maximum":1},"subscription_detected":{"type":"boolean"},"recurrence_interval":{"type":"string","nullable":true,"enum":["weekly","monthly","quarterly","annual"]},"next_expected_charge":{"type":"string","nullable":true,"format":"date-time"},"recall_detected":{"type":"boolean"},"recalls":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["cpsc","fda_drug","fda_food","nhtsa"]},"recall_id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"date":{"type":"string"},"url":{"type":"string","nullable":true}}}},"recommended_gl_code":{"type":"string","nullable":true,"example":"7030"},"recommended_tax_treatment":{"type":"object","properties":{"treatment":{"type":"string","enum":["fully_deductible","partially_deductible","capitalized","non_deductible","unknown"]},"basis":{"type":"string","description":"IRS code citation and rationale"},"category_anchor":{"type":"string","nullable":true},"disclaimer":{"type":"string","example":"Informational only. Not tax advice. Consult a qualified tax professional for your specific situation."}}},"related_purchases":{"type":"array","maxItems":10,"items":{"type":"object","properties":{"id":{"type":"string"},"merchant_name":{"type":"string","nullable":true},"amount":{"type":"number"},"timestamp":{"type":"string","format":"date-time"},"relation":{"type":"string","enum":["same_entity_same_merchant","same_po","same_gl_cost_center"]}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"experimental","x-viacle-audience":["evaluation-only"],"x-viacle-authority-boundary":"Semantics and support commitment are not generally available."}},"/purchases/{id}/return-eligible":{"get":{"tags":["Purchases"],"summary":"Check return eligibility for a purchase","description":"Returns a structured `return_eligibility` object with the deadline, days remaining, and live warranty status — computed in real time from the merchant record.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"responses":{"200":{"description":"Return eligibility result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnEligibility"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases/{id}/receipt-link":{"post":{"tags":["Purchases"],"summary":"Generate a shareable receipt link","description":"Creates a signed, time-limited public URL that renders the purchase record without authentication. Store the `token` — it is not retrievable after creation.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"$ref":"#/components/parameters/PurchaseId"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"expires_in_days":{"type":"integer","minimum":1,"maximum":365,"description":"Days until the link expires. Omit for a non-expiring link."}}}}}},"responses":{"201":{"description":"Receipt link created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiptLink"}}}},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/expenses/summary":{"get":{"tags":["Expenses"],"summary":"Aggregate spend by dimension","description":"Groups purchases by `department`, `gl_code`, `cost_center`, `entity_id`, or `approval_status` and returns total amount and count per group, ordered by spend descending.","security":[{"BearerAuth":["expenses:read"]}],"parameters":[{"name":"group_by","in":"query","required":true,"schema":{"type":"string","enum":["department","gl_code","cost_center","entity_id","approval_status"]}},{"name":"date_from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"date_to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"entity_id","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Expense summary","content":{"application/json":{"schema":{"type":"object","properties":{"group_by":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ExpenseSummaryItem"}}}}}}},"400":{"$ref":"#/components/responses/InvalidRequest"}},"x-viacle-exposure":"experimental","x-viacle-audience":["evaluation-only"],"x-viacle-authority-boundary":"Semantics and support commitment are not generally available."}},"/expenses/approvals":{"get":{"tags":["Expenses"],"summary":"Approval workflow audit trail","description":"Queryable log of all approval state transitions (approved, rejected, reimbursed) across purchases. Backed by `event_log` entries written on every transition.","security":[{"BearerAuth":["expenses:read"]}],"parameters":[{"name":"date_from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"date_to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"entity_id","in":"query","schema":{"type":"string"}},{"name":"approval_status","in":"query","schema":{"type":"string","enum":["approved","rejected","reimbursed"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":1000}}],"responses":{"200":{"description":"Approval audit entries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApprovalAuditEntry"}},"has_more":{"type":"boolean"}}}}}}},"x-viacle-exposure":"experimental","x-viacle-audience":["evaluation-only"],"x-viacle-authority-boundary":"Semantics and support commitment are not generally available."}},"/tax/generate-pdf":{"post":{"tags":["Tax"],"summary":"Generate a tax document PDF","description":"Produces a ready-to-file or importable PDF from a stored FDX tax statement via the Tax Doc Hub (ITIPS) integration. Returns `application/pdf`. Requires `TAX_DOC_HUB_API_KEY` to be configured.","security":[{"BearerAuth":["tax:read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["statement_id","fdx_class"],"properties":{"statement_id":{"type":"string","description":"ID of the stored FDX tax statement"},"fdx_class":{"type":"string","example":"Tax1099Nec","description":"FDX document class (e.g. Tax1099Nec, TaxW2, Tax1099K)"},"pdf_type":{"type":"string","enum":["downloadPdf4","printPdf1","printPdf5"],"default":"downloadPdf4"},"importable":{"type":"boolean","default":false,"description":"When true, returns an importable XML-embedded PDF rather than a print-ready copy"}}}}}},"responses":{"200":{"description":"PDF binary","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"503":{"description":"TAX_DOC_HUB_API_KEY not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-viacle-exposure":"vertical-adapter","x-viacle-audience":["institutional-distributor","domain-system"],"x-viacle-authority-boundary":"Preserves or delivers domain evidence without operating the adjacent domain workflow."}},"/stream":{"get":{"tags":["Streaming"],"summary":"Subscribe to real-time purchase events (SSE)","description":"Opens a Server-Sent Events stream backed by PostgreSQL `LISTEN/NOTIFY`. Each message is a JSON-serialised `event_log` entry. The stream emits a heartbeat every 15 s to prevent proxy timeouts. Reconnect by re-opening the connection — pass `last_event_id` to replay missed events.","security":[{"BearerAuth":[]}],"parameters":[{"name":"entity_id","in":"query","schema":{"type":"string"},"description":"Filter events to a single entity"},{"name":"event_type","in":"query","schema":{"type":"string"},"description":"Filter to a specific event type, e.g. purchase.created"},{"name":"last_event_id","in":"query","schema":{"type":"integer"},"description":"Replay events with sequence > this value"}],"responses":{"200":{"description":"Event stream","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/events":{"get":{"tags":["Streaming"],"summary":"Replay event log (polling alternative to SSE)","description":"Returns a page of `event_log` entries. Use `from_seq` and `to_seq` for deterministic replay windows, or standard date filters for time-range queries.","security":[{"BearerAuth":[]}],"parameters":[{"name":"from_seq","in":"query","schema":{"type":"integer"}},{"name":"to_seq","in":"query","schema":{"type":"integer"}},{"name":"entity_id","in":"query","schema":{"type":"string"}},{"name":"event_type","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":500}}],"responses":{"200":{"description":"Event log page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"has_more":{"type":"boolean"}}}}}}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/oauth/token":{"post":{"tags":["Auth"],"summary":"Issue an OAuth 2.0 access token (client credentials)","description":"Exchanges `client_id` + `client_secret` for a short-lived JWT. Pass the JWT as `Authorization: Bearer <token>` on subsequent requests.","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"]},"client_id":{"type":"string"},"client_secret":{"type":"string"},"scope":{"type":"string","description":"Space-separated scopes, e.g. `purchases:read purchases:write`"}}}}}},"responses":{"200":{"description":"Access token","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","enum":["bearer"]},"expires_in":{"type":"integer","example":3600},"scope":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/ingest/iso20022":{"post":{"tags":["Connectors"],"summary":"Ingest an ISO 20022 XML message","description":"Accepts raw ISO 20022 XML (pain.001, pacs.008, camt.052, camt.053, camt.054, remt.001). camt.052 and camt.053 are accepted statement evidence; remt.001 is accepted remittance evidence. camt.035 Proprietary Format Investigation is ecosystem context only: it is not accepted for ingest and no Viacle profile is claimed. Auto-detects accepted message types and creates a Purchase Object while preserving source metadata. This parser does not provide live SWIFT connectivity, signing, or XSD validation.","security":[{"BearerAuth":["purchases:write"]}],"requestBody":{"required":true,"content":{"text/xml":{"schema":{"type":"string","example":"<?xml ...?>"}}}},"responses":{"201":{"description":"Purchase created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/ingest/fednow":{"post":{"tags":["Connectors"],"summary":"Ingest a FedNow payment notification","description":"Accepts FedNow JSON payment notifications (pacs.008-derived). Creates a Purchase Object with `rail_source: fednow`.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Purchase created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/ingest/sepa_instant":{"post":{"tags":["Connectors"],"summary":"Ingest a SEPA Instant Credit Transfer","description":"Accepts SEPA Instant JSON or XML messages. Creates a Purchase Object with `rail_source: sepa_instant`.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Purchase created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/ingest/upi":{"post":{"tags":["Connectors"],"summary":"Ingest a UPI payment","description":"Accepts UPI payment JSON. Creates a Purchase Object with `rail_source: upi`.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"description":"Purchase created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/ingest/stripe":{"post":{"tags":["Connectors"],"summary":"Ingest a Stripe webhook event","description":"Accepts `charge.succeeded`, `payment_intent.succeeded`, and `checkout.session.completed` events. Payload signature verified via `Stripe-Signature` header when `STRIPE_WEBHOOK_SECRET` is configured. Line items extracted from Checkout Session cart contents, Invoice line items, and (on `payment_intent.succeeded`) Level 2/3 card data via `amount_details.line_items` when the merchant has Enhanced Scheme Data enabled.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"data":{"type":"object"}}}}}},"responses":{"200":{"description":"Event type acknowledged but not ingested"},"201":{"description":"Purchase created from Stripe event"},"400":{"description":"Invalid signature or payload"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/ingest/primer":{"post":{"tags":["Connectors"],"summary":"Ingest a Primer webhook event","description":"Accepts `PAYMENT.STATUS_CHANGED` (status `SETTLED`) and `REFUND.STATUS_CHANGED` (status `SETTLED`) events from Primer. Signature verified via `X-Signature-Primary` (HMAC-SHA256 of raw body, base64-encoded) when `PRIMER_WEBHOOK_SIGNING_SECRET` is configured. Supports `X-Signature-Secondary` during signing secret rotation. Replay attacks rejected via `signedAt` field (3-minute window). Line items from `data.payment.order.lineItems` are ingested directly as purchase line items.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["eventType","data"],"properties":{"eventType":{"type":"string","enum":["PAYMENT.STATUS_CHANGED","REFUND.STATUS_CHANGED"],"example":"PAYMENT.STATUS_CHANGED"},"eventId":{"type":"string","example":"evt_abc123"},"signedAt":{"type":"number","description":"Unix epoch seconds at which Primer signed this payload. Used for 3-minute replay-attack window.","example":1717228800},"data":{"type":"object","description":"Exactly one of `payment` or `refund` will be present depending on `eventType`.","properties":{"payment":{"type":"object","description":"Present when `eventType` is `PAYMENT.STATUS_CHANGED`.","properties":{"id":{"type":"string","example":"pay_xyz789"},"date":{"type":"string","format":"date-time","example":"2024-06-01T10:00:00.000Z"},"dateUpdated":{"type":"string","format":"date-time","description":"Fallback timestamp used when `date` is absent."},"status":{"type":"string","example":"SETTLED","description":"Only `SETTLED` payments are ingested."},"orderId":{"type":"string","example":"order-456"},"currencyCode":{"type":"string","example":"USD"},"amount":{"type":"number","description":"Amount in minor units (e.g. cents for USD).","example":4999},"order":{"type":"object","properties":{"lineItems":{"type":"array","description":"Individual line items within the order. Items with `amount: 0` are skipped.","items":{"type":"object","properties":{"itemId":{"type":"string","example":"sku-001"},"description":{"type":"string","example":"Running Shoes"},"amount":{"type":"number","description":"Line item total in minor units.","example":4999},"quantity":{"type":"number","example":1}}}}}},"paymentMethodToken":{"type":"object","properties":{"paymentMethodType":{"type":"string","enum":["PAYMENT_CARD","PAYPAL","KLARNA","APPLE_PAY","GOOGLE_PAY"],"example":"PAYMENT_CARD"},"last4Digits":{"type":"string","example":"4242"},"network":{"type":"string","example":"Visa","description":"Card network used to derive `card_visa`, `card_mastercard`, etc."}}},"customer":{"type":"object","properties":{"firstName":{"type":"string","example":"Jane"},"lastName":{"type":"string","example":"Doe"},"emailAddress":{"type":"string","format":"email","example":"jane@example.com"}}},"processor":{"type":"object","description":"Underlying processor used by Primer to settle the payment. Its `name` is stored as `merchant_name`.","properties":{"name":{"type":"string","example":"STRIPE"}}}}},"refund":{"type":"object","description":"Present when `eventType` is `REFUND.STATUS_CHANGED`.","properties":{"id":{"type":"string","example":"ref_abc123"},"date":{"type":"string","format":"date-time","example":"2024-06-02T11:00:00.000Z"},"status":{"type":"string","example":"SETTLED","description":"Only `SETTLED` refunds are ingested."},"amount":{"type":"number","description":"Refund amount in minor units.","example":2500},"currency":{"type":"string","example":"USD"},"orderId":{"type":"string","example":"order-456"},"paymentId":{"type":"string","example":"pay_xyz789","description":"Used in memo when `orderId` is absent."}}}}}}},"examples":{"payment":{"summary":"Settled payment with line items","value":{"eventType":"PAYMENT.STATUS_CHANGED","eventId":"evt_abc123","signedAt":1717228800,"data":{"payment":{"id":"pay_xyz789","date":"2024-06-01T10:00:00.000Z","status":"SETTLED","orderId":"order-456","currencyCode":"USD","amount":4999,"order":{"lineItems":[{"itemId":"sku-001","description":"Running Shoes","amount":4999,"quantity":1}]},"paymentMethodToken":{"paymentMethodType":"PAYMENT_CARD","last4Digits":"4242","network":"Visa"},"customer":{"firstName":"Jane","lastName":"Doe","emailAddress":"jane@example.com"},"processor":{"name":"STRIPE"}}}}},"refund":{"summary":"Settled refund","value":{"eventType":"REFUND.STATUS_CHANGED","eventId":"evt_ref001","signedAt":1717315200,"data":{"refund":{"id":"ref_abc123","date":"2024-06-02T11:00:00.000Z","status":"SETTLED","amount":2500,"currency":"USD","orderId":"order-456","paymentId":"pay_xyz789"}}}}}}}},"responses":{"200":{"description":"Event type received but not ingested (e.g. non-SETTLED status, unrecognised event type)."},"201":{"description":"Purchase record created from Primer event."},"401":{"description":"Webhook signature invalid — `X-Signature-Primary` (and `X-Signature-Secondary` if provided) did not match the HMAC-SHA256 base64 of the raw body using `PRIMER_WEBHOOK_SIGNING_SECRET`."},"408":{"description":"Replay attack detected — `signedAt` is more than 3 minutes old."},"422":{"description":"Could not extract a valid non-zero amount from the event payload."},"500":{"description":"Internal error during purchase creation."}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/ingest/coinbase_commerce":{"post":{"tags":["Connectors"],"summary":"Ingest a Coinbase Commerce webhook event","description":"Accepts `charge:confirmed` and `charge:resolved` events. HMAC-SHA256 signature verified via `X-CC-Webhook-Signature`. Supports BTC, ETH, USDC, SOL.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Event type acknowledged but not ingested"},"201":{"description":"Purchase created from Coinbase Commerce event"},"400":{"description":"Invalid signature or payload"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/ingest/shopify":{"post":{"tags":["Connectors"],"summary":"Ingest a Shopify webhook (orders/paid)","description":"Accepts `orders/paid` webhook events from Shopify. HMAC-SHA256 signature verified via `X-Shopify-Hmac-Sha256` when a `webhook_secret` is configured on the connector. Creates a Purchase Object from the order.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Topic acknowledged but not ingested"},"201":{"description":"Purchase created from Shopify order"},"400":{"description":"Invalid signature"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/ingest/nacha_ach":{"post":{"tags":["Connectors"],"summary":"Ingest a NACHA ACH file","description":"Parses 94-character fixed-width NACHA ACH files. Supports all standard SEC codes (PPD, CCD, CTX, WEB, TEL, POP, ARC, RCK). Pre-notes and zero-dollar entries are skipped. Returns 207 Multi-Status with per-entry disposition.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"text/plain":{"schema":{"type":"string","description":"Raw NACHA file text"}}}},"responses":{"207":{"description":"Multi-status — inspect each entry result individually"},"400":{"$ref":"#/components/responses/InvalidRequest"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/ingest/x402":{"post":{"tags":["Connectors"],"summary":"Ingest an x402 payment proof","description":"Accepts cryptographically signed HTTP 402 payment proofs (USDC on Base or other EVM chains). Proof structure and expiry are validated before creating a Purchase Object with `rail_source: x402`.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["x402Version","scheme","network","payload"],"properties":{"x402Version":{"type":"integer","example":1},"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"base-mainnet"},"payload":{"type":"object","properties":{"authorization":{"type":"object"},"signature":{"type":"string"}}}}}}}},"responses":{"201":{"description":"Purchase created from x402 proof","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/connectors/ingest/stables":{"post":{"tags":["Connectors"],"summary":"Ingest a Stables.money webhook event","description":"Accepts Stables.money webhook events for stablecoin payment completions. Supported types: `WEBHOOK_EVENT_TYPE_PAYMENT_COMPLETED`, `WEBHOOK_EVENT_TYPE_TRANSFER_COMPLETED`, `WEBHOOK_EVENT_TYPE_OFFRAMP_COMPLETED`, `WEBHOOK_EVENT_TYPE_ONRAMP_COMPLETED`. Payload signature verified via `stables-signature` header (HMAC-SHA256 of raw body, hex-encoded, optionally prefixed with `sha256=`) when `STABLES_WEBHOOK_SIGNING_SECRET` is configured. Unknown event types return 200 acknowledged without ingestion. Creates a Purchase Object with `rail_source: stables`.","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","created_at","data"],"properties":{"id":{"type":"string","example":"evt_stb_abc123"},"type":{"type":"string","enum":["WEBHOOK_EVENT_TYPE_PAYMENT_COMPLETED","WEBHOOK_EVENT_TYPE_TRANSFER_COMPLETED","WEBHOOK_EVENT_TYPE_OFFRAMP_COMPLETED","WEBHOOK_EVENT_TYPE_ONRAMP_COMPLETED"],"example":"WEBHOOK_EVENT_TYPE_PAYMENT_COMPLETED"},"created_at":{"type":"string","format":"date-time","example":"2026-05-25T10:00:00Z"},"data":{"type":"object","required":["id","amount","currency"],"properties":{"id":{"type":"string","example":"pay_xyz789"},"customer_id":{"type":"string","example":"cust_42bc"},"amount":{"type":"string","example":"250.00"},"currency":{"type":"string","example":"USDC"},"network":{"type":"string","example":"base"},"status":{"type":"string","example":"COMPLETED"},"type":{"type":"string","enum":["ONRAMP","OFFRAMP","TRANSFER"],"example":"ONRAMP"},"external_reference":{"type":"string","description":"Caller-controlled idempotency key. Used as `reference_id` when present.","example":"inv-2026-00042"},"recipient":{"type":"object","properties":{"name":{"type":"string","example":"Acme Corp"},"address":{"type":"string","example":"0xAbCd...1234"}}},"sender":{"type":"object","properties":{"name":{"type":"string","example":"Alice Ltd"},"customer_id":{"type":"string","example":"cust_a1"}}},"completed_at":{"type":"string","format":"date-time","example":"2026-05-25T10:01:00Z"}}}}}}}},"responses":{"200":{"description":"Event type acknowledged but not ingested"},"201":{"description":"Purchase created from Stables event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"401":{"description":"Invalid webhook signature"},"422":{"description":"Could not extract a valid amount from the event"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases/{id}/splits":{"post":{"tags":["Purchases"],"summary":"Create cost splits for a purchase","description":"Splits a purchase across multiple cost centers, entities, or labels. The sum of all split amounts must equal the purchase total (within ±0.02).","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Purchase public ID (pur_vc_…)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSplitsBody"}}}},"responses":{"201":{"description":"Splits created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseSplitsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Split amounts do not sum to purchase total"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"get":{"tags":["Purchases"],"summary":"List cost splits for a purchase","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Purchase public ID (pur_vc_…)"}],"responses":{"200":{"description":"Splits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseSplitsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"delete":{"tags":["Purchases"],"summary":"Delete all cost splits for a purchase","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Purchase public ID (pur_vc_…)"}],"responses":{"200":{"description":"Splits deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"purchase_id":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/purchases/{id}/dispute":{"post":{"tags":["Purchases"],"summary":"Open a dispute on a purchase","description":"Creates a dispute record. Use `freight_reason_code` for freight billing disputes; omit for general billing disputes. Only one active dispute per purchase is allowed.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Purchase public ID (pur_vc_…)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDisputeBody"}}}},"responses":{"201":{"description":"Dispute opened","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dispute"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"An active dispute already exists for this purchase"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"get":{"tags":["Purchases"],"summary":"Get the dispute for a purchase","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Purchase public ID (pur_vc_…)"}],"responses":{"200":{"description":"Dispute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dispute"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."},"patch":{"tags":["Purchases"],"summary":"Update a dispute","description":"Advance dispute status, record a merchant response, or link a correction purchase. Valid status transitions: `open` → `pending_correction` → `resolved` or `rejected`; `open` → `withdrawn`.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Purchase public ID (pur_vc_…)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDisputeBody"}}}},"responses":{"200":{"description":"Updated dispute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dispute"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/disputes":{"get":{"tags":["Purchases"],"summary":"List all disputes","description":"Returns all disputes for the API key, ordered by creation time descending. Filter by status to monitor open or pending disputes.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["open","pending_correction","resolved","rejected","withdrawn"]},"description":"Filter by dispute status"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Dispute list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Dispute"}},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"x-viacle-exposure":"core","x-viacle-audience":["institutional-distributor","financial-system"],"x-viacle-authority-boundary":"Preserves attributable source facts and lifecycle state; does not replace source-system or human authority."}},"/ap-rules":{"get":{"tags":["Commercial"],"summary":"List AP automation rules","description":"Returns all AP auto-evaluation rules for the API key's organisation in priority order.","security":[{"BearerAuth":["purchases:read"]}],"responses":{"200":{"description":"Rule list","content":{"application/json":{"schema":{"type":"object","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApRule"}},"has_more":{"type":"boolean","enum":[false]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."},"post":{"tags":["Commercial"],"summary":"Create an AP automation rule","description":"Adds a tenant-scoped rule evaluated at ingest and on manual re-evaluation. Every supplied condition must match. Action values are `auto_approve` and `route_to`.","security":[{"BearerAuth":["purchases:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApRule"}}}},"responses":{"201":{"description":"Rule created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApRule"}}}},"400":{"description":"Invalid rule definition"},"401":{"$ref":"#/components/responses/Unauthorized"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/ap-rules/{id}":{"patch":{"tags":["Commercial"],"summary":"Update an AP automation rule","description":"Updates any supplied rule fields. Omitted fields remain unchanged.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateApRule"}}}},"responses":{"200":{"description":"Rule updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApRule"}}}},"400":{"description":"Invalid rule definition"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."},"delete":{"tags":["Commercial"],"summary":"Delete an AP rule","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Rule deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/purchases/{id}/ap-evaluate":{"post":{"tags":["Commercial"],"summary":"Re-evaluate AP rules for a purchase","description":"Runs active AP rules in priority order, applies the first matching action, and returns the rule decision, trust signal, skip reasons, and any automatic journal-entry posting result.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Purchase public ID (pur_vc_…)"}],"responses":{"200":{"description":"Evaluation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApEvaluation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/purchases/{id}/ap-decision":{"get":{"tags":["Commercial"],"summary":"Get the latest durable AP decision","description":"Returns safe normalized AP verification and correlation results with bounded immutable decision history. Raw source payloads are never returned.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Purchase public ID (pur_vc_…)"}],"responses":{"200":{"description":"Latest AP decision or an explicit not-evaluated representation"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/purchases/{id}/journal-entry":{"post":{"tags":["Commercial"],"summary":"Generate a journal entry draft","description":"Compute or recompute a journal entry draft for a purchase from its GL code, cost center, amount, and fraud/duplicate state. `debit_account` is derived from the purchase GL code; `credit_account` starts as `null` and must be set via PATCH before posting.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Purchase public ID (pur_vc_…)"}],"responses":{"201":{"description":"Draft created or regenerated (the endpoint returns 201 for both cases)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JournalEntryDraft"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The draft has already been posted or a posting attempt is in progress"},"422":{"description":"Insufficient data — purchase is missing GL code or amount"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."},"patch":{"tags":["Commercial"],"summary":"Configure draft accounts","description":"Set or update `debit_account` and/or `credit_account` on an existing draft. Both must be non-null before the draft can be posted to an ERP. Omit a field to leave it unchanged. Returns 409 if the draft has already been posted.","security":[{"BearerAuth":["purchases:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Purchase public ID (pur_vc_…)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"debit_account":{"type":"string","minLength":1,"maxLength":200,"nullable":true,"description":"GL account name or code to debit (expense side). Omit to leave unchanged."},"credit_account":{"type":"string","minLength":1,"maxLength":200,"nullable":true,"description":"GL account name or code to credit (typically Accounts Payable). Omit to leave unchanged."}}}}}},"responses":{"200":{"description":"Draft updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JournalEntryDraft"}}}},"400":{"description":"No fields provided — supply at least one of debit_account or credit_account"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Draft is already posted or a posting attempt is in progress — accounts cannot be changed"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."},"get":{"tags":["Commercial"],"summary":"Retrieve a journal entry draft","description":"Returns the current journal entry draft for a purchase, or 404 if none has been generated yet.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Purchase public ID (pur_vc_…)"}],"responses":{"200":{"description":"Journal entry draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JournalEntryDraft"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/reconciliation":{"get":{"tags":["Reconciliation"],"summary":"Retrieve the reconciliation workspace","description":"Returns the caller's cross-source purchase records grouped into matched, suggested (needs review), and unmatched buckets. Purchase IDs are public purchase IDs.","security":[{"BearerAuth":["purchases:read"]}],"responses":{"200":{"description":"Reconciliation workspace","content":{"application/json":{"schema":{"type":"object","required":["matched","suggested","unmatched","stats"],"properties":{"matched":{"type":"array","items":{"$ref":"#/components/schemas/ReconciliationItem"}},"suggested":{"type":"array","items":{"$ref":"#/components/schemas/ReconciliationItem"}},"unmatched":{"type":"array","items":{"$ref":"#/components/schemas/ReconciliationItem"}},"stats":{"$ref":"#/components/schemas/ReconciliationStats"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/reconciliation/run":{"post":{"tags":["Reconciliation"],"summary":"Run reconciliation for eligible purchases","description":"Scores unlinked records in the caller's workspace. High-confidence links are accepted automatically; lower-confidence links appear in the suggested bucket for review.","security":[{"BearerAuth":["purchases:write"]}],"responses":{"200":{"description":"Run summary","content":{"application/json":{"schema":{"type":"object","required":["auto_linked","suggested","no_match","processed"],"properties":{"auto_linked":{"type":"integer"},"suggested":{"type":"integer"},"no_match":{"type":"integer"},"processed":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/reconciliation/confirm":{"post":{"tags":["Reconciliation"],"summary":"Confirm a suggested reconciliation match","description":"Promotes an existing suggested link to a confirmed match. The canonical ID must match the current suggestion; callers cannot substitute a different target.","security":[{"BearerAuth":["purchases:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["signal_id","canonical_id"],"properties":{"signal_id":{"type":"string","description":"Suggested signal purchase public ID"},"canonical_id":{"type":"string","description":"Existing canonical purchase public ID"}}}}}},"responses":{"200":{"description":"Match confirmed"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Match is stale, ineligible, or already decided"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/reconciliation/dismiss":{"post":{"tags":["Reconciliation"],"summary":"Dismiss a reconciliation record","description":"Removes a record from the reconciliation workspace and prevents it from being re-proposed by a later workspace run.","security":[{"BearerAuth":["purchases:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["receipt_id"],"properties":{"receipt_id":{"type":"string","description":"Purchase public ID"}}}}}},"responses":{"200":{"description":"Record dismissed"},"404":{"$ref":"#/components/responses/NotFound"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/analytics/receipt-compliance":{"get":{"tags":["Commercial"],"summary":"Measure receipt evidence compliance","description":"Returns overall and grouped rates for purchases that include receipt evidence.","security":[{"BearerAuth":["analytics:read"]}],"parameters":[{"name":"group_by","in":"query","schema":{"type":"string","enum":["entity_id","department","cost_center"],"default":"entity_id"}},{"name":"date_from","in":"query","schema":{"type":"string","format":"date"}},{"name":"date_to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Receipt compliance summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReceiptComplianceSummary"}}}},"400":{"description":"Invalid grouping or date filter"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/analytics/spending-by-tag":{"get":{"tags":["Commercial"],"summary":"Summarize spending by tag","description":"Returns purchase count, spend, and leading merchants for each purchase tag.","security":[{"BearerAuth":["analytics:read"]}],"parameters":[{"name":"date_from","in":"query","schema":{"type":"string","format":"date"}},{"name":"date_to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Spending by tag","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpendingByTagSummary"}}}},"400":{"description":"Invalid date filter"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/analytics/payment-rails":{"get":{"tags":["Commercial"],"summary":"Summarize spending by payment rail","description":"Returns normalized payment-rail counts, spend, and spend share for the tenant.","security":[{"BearerAuth":["analytics:read"]}],"parameters":[{"name":"entity_id","in":"query","schema":{"type":"string"}},{"name":"date_from","in":"query","schema":{"type":"string","format":"date"}},{"name":"date_to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Payment rail breakdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRailsSummary"}}}},"400":{"description":"Invalid date filter"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/analytics/vendor-concentration":{"get":{"tags":["Commercial"],"summary":"Measure vendor concentration","description":"Returns the highest-spend vendors and each vendor's share of the filtered portfolio.","security":[{"BearerAuth":["analytics:read"]}],"parameters":[{"name":"entity_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"default":10}},{"name":"date_from","in":"query","schema":{"type":"string","format":"date"}},{"name":"date_to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Vendor concentration summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendorConcentrationSummary"}}}},"400":{"description":"Invalid limit or date filter"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}},"/close/readiness":{"get":{"tags":["Commercial"],"summary":"Accounting close readiness","description":"Evaluates every purchase in the period for GL code, cost center, duplicate, fraud, and completion status. Returns the exact purchase-level blockers, capped at 500 exceptions.","security":[{"BearerAuth":["purchases:read"]}],"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Period start (YYYY-MM-DD). Defaults to first day of current month."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Period end (YYYY-MM-DD). Defaults to today."}],"responses":{"200":{"description":"Close readiness report","content":{"application/json":{"schema":{"type":"object","required":["period_from","period_to","total_records","ready_records","close_readiness_pct","exception_breakdown","exceptions","_exceptions_truncated","benchmark"],"properties":{"period_from":{"type":"string","format":"date"},"period_to":{"type":"string","format":"date"},"total_records":{"type":"integer","minimum":0},"ready_records":{"type":"integer","minimum":0},"close_readiness_pct":{"type":"integer","minimum":0,"maximum":100,"nullable":true,"description":"Percentage of records that pass every close-readiness criterion; null when the period has no records."},"exception_breakdown":{"$ref":"#/components/schemas/CloseReadinessBreakdown"},"exceptions":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/CloseReadinessException"}},"_exceptions_truncated":{"type":"boolean"},"benchmark":{"allOf":[{"$ref":"#/components/schemas/CloseReadinessBenchmark"}],"nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"x-viacle-exposure":"projection","x-viacle-audience":["financial-system","controller-organization"],"x-viacle-authority-boundary":"Derived context for an authorized consuming system; not ledger truth or certification."}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key (vi_live_sk_... or vi_test_sk_...). Pass as `Authorization: Bearer <key>`. Alternatively, use OAuth 2.0 client credentials at `POST /api/v1/oauth/token`."},"ConsumerSession":{"type":"apiKey","in":"cookie","name":"consumer_session","description":"Authenticated consumer session cookie. Consumer routes are not authorized by API keys."},"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/api/v1/oauth/token","scopes":{"purchases:read":"Read purchase objects","purchases:write":"Create and mutate purchase objects","tax:read":"Read tax summaries and recurring merchant data","tax:write":"Write tax statements","compliance:read":"Read compliance events","compliance:write":"Append compliance events","policies:read":"Read expense policies","policies:write":"Create and mutate expense policies","expenses:write":"Create mileage and per-diem expenses","expenses:read":"Read expense summaries and approval audit trail","analytics:read":"Read tenant-scoped purchase analytics","fdx:read":"Read FDX resources","fdx:write":"Write FDX resources"}}}}},"parameters":{"PurchaseId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Purchase public ID (pur_vc_...) or internal UUID"},"EntityId":{"name":"entityId","in":"path","required":true,"schema":{"type":"string"},"description":"Entity internal UUID"},"CommercialCaseId":{"name":"caseId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":500}},"ProjectionKey":{"name":"projectionKey","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":500}},"AirwallexDeliveryId":{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":500}},"ConsumerGrantId":{"name":"grantId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":500}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidRequest":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"CommercialCase":{"type":"object","additionalProperties":false,"required":["id","caseReference","caseType","lifecycleState","resolutionState","completenessState","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"caseReference":{"type":"string"},"caseType":{"type":"string"},"lifecycleState":{"type":"string"},"resolutionState":{"type":"string"},"completenessState":{"type":"string"},"materiality":{"$ref":"#/components/schemas/PortablePurchaseMoney"},"effectiveAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CommercialCaseObject":{"type":"object","additionalProperties":false,"required":["id","objectType","sourceSystem","nativeId","retentionState","ingestedAt"],"properties":{"id":{"type":"string"},"objectType":{"type":"string"},"sourceSystem":{"type":"string"},"connectorId":{"type":"string"},"nativeId":{"type":"string"},"nativeVersion":{"type":"string"},"payloadHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"sourceRecordType":{"type":"string"},"retentionState":{"type":"string","enum":["available","restricted","purged"]},"effectiveAt":{"type":"string","format":"date-time"},"observedAt":{"type":"string","format":"date-time"},"ingestedAt":{"type":"string","format":"date-time"}}},"CommercialCaseAssertion":{"type":"object","additionalProperties":false,"required":["id","subjectObjectId","field","value","valueType","sourceSystem","authority","createdAt"],"properties":{"id":{"type":"string"},"subjectObjectId":{"type":"string"},"sourceObjectId":{"type":"string"},"field":{"type":"string"},"value":{},"restricted":{"type":"boolean"},"valueType":{"type":"string"},"sourceSystem":{"type":"string"},"authority":{"type":"string"},"confidence":{"type":"number"},"effectiveAt":{"type":"string","format":"date-time"},"observedAt":{"type":"string","format":"date-time"},"supersedesAssertionId":{"type":"string"},"correctionOfAssertionId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"CommercialCaseLink":{"type":"object","additionalProperties":false,"required":["id","sourceObjectId","targetObjectId","linkType","state","createdAt"],"properties":{"id":{"type":"string"},"sourceObjectId":{"type":"string"},"targetObjectId":{"type":"string"},"linkType":{"type":"string"},"state":{"type":"string"},"confidence":{"type":"number"},"rationale":{"type":"string"},"effectiveAt":{"type":"string","format":"date-time"},"supersedesLinkId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"CommercialCaseAllocation":{"type":"object","additionalProperties":false,"required":["id","sourceObjectId","targetObjectId","amount","reason","state","createdAt"],"properties":{"id":{"type":"string"},"sourceObjectId":{"type":"string"},"targetObjectId":{"type":"string"},"amount":{"$ref":"#/components/schemas/PortablePurchaseMoney"},"reason":{"type":"string"},"state":{"type":"string"},"effectiveAt":{"type":"string","format":"date-time"},"reversalOfAllocationId":{"type":"string"},"supersedesAllocationId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"CommercialCaseDecision":{"type":"object","additionalProperties":false,"required":["id","decisionType","authority","effectiveAt","createdAt"],"properties":{"id":{"type":"string"},"decisionType":{"type":"string"},"authority":{"type":"string","enum":["authoritative","attested","observed","inferred","user_confirmed","policy"]},"effectiveAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"CommercialCaseDetail":{"type":"object","additionalProperties":false,"required":["case","objects","assertions","links","allocations","decisions"],"properties":{"case":{"$ref":"#/components/schemas/CommercialCase"},"objects":{"type":"array","items":{"$ref":"#/components/schemas/CommercialCaseObject"}},"assertions":{"type":"array","items":{"$ref":"#/components/schemas/CommercialCaseAssertion"}},"links":{"type":"array","items":{"$ref":"#/components/schemas/CommercialCaseLink"}},"allocations":{"type":"array","items":{"$ref":"#/components/schemas/CommercialCaseAllocation"}},"decisions":{"type":"array","items":{"$ref":"#/components/schemas/CommercialCaseDecision"}}}},"CommercialCasePage":{"type":"object","additionalProperties":false,"required":["data","next_cursor"],"properties":{"data":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/CommercialCase"}},"next_cursor":{"type":["string","null"]}}},"CommercialCaseProjection":{"type":"object","additionalProperties":false,"required":["projection_key","status","commercial_case_id","attempt_count"],"properties":{"projection_key":{"type":"string"},"status":{"type":"string"},"commercial_case_id":{"type":"string"},"attempt_count":{"type":"integer","minimum":0},"updated_at":{"type":"string","format":"date-time"}}},"CommercialCaseObjectList":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommercialCaseObject"}}}},"CommercialCaseAssertionList":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommercialCaseAssertion"}}}},"CommercialCaseLinkList":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommercialCaseLink"}}}},"CommercialCaseAllocationList":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommercialCaseAllocation"}}}},"CommercialCaseDecisionList":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommercialCaseDecision"}}}},"CommercialCasePublicAssertionValue":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"type":["string","number","boolean","null"]}},{"$ref":"#/components/schemas/PortablePurchaseMoney"}]},"CommercialCaseConflict":{"type":"object","additionalProperties":false,"required":["field","status","assertions"],"properties":{"field":{"type":"string"},"status":{"const":"unresolved"},"assertions":{"type":"array","minItems":2,"items":{"type":"object","additionalProperties":false,"required":["value","valueType","sourceSystem","authority"],"properties":{"value":{"$ref":"#/components/schemas/CommercialCasePublicAssertionValue"},"valueType":{"type":"string"},"sourceSystem":{"type":"string"},"authority":{"type":"string"},"effectiveAt":{"type":"string","format":"date-time"},"observedAt":{"type":"string","format":"date-time"}}}}}},"CommercialCaseConflictList":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommercialCaseConflict"}}}},"CommercialCaseTimelineEvent":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type","occurredAt","objectType","sourceSystem"],"properties":{"type":{"const":"object"},"occurredAt":{"type":"string","format":"date-time"},"objectType":{"type":"string"},"sourceSystem":{"type":"string"}}},{"type":"object","additionalProperties":false,"required":["type","occurredAt","field","value","valueType","sourceSystem","authority"],"properties":{"type":{"const":"assertion"},"occurredAt":{"type":"string","format":"date-time"},"field":{"type":"string"},"value":{"$ref":"#/components/schemas/CommercialCasePublicAssertionValue"},"valueType":{"type":"string"},"sourceSystem":{"type":"string"},"authority":{"type":"string"}}},{"type":"object","additionalProperties":false,"required":["type","occurredAt","linkType","state"],"properties":{"type":{"const":"link"},"occurredAt":{"type":"string","format":"date-time"},"linkType":{"type":"string"},"state":{"type":"string"}}},{"type":"object","additionalProperties":false,"required":["type","occurredAt","amount","state"],"properties":{"type":{"const":"allocation"},"occurredAt":{"type":"string","format":"date-time"},"amount":{"$ref":"#/components/schemas/PortablePurchaseMoney"},"state":{"type":"string"}}},{"type":"object","additionalProperties":false,"required":["type","occurredAt","decisionType","authority"],"properties":{"type":{"const":"decision"},"occurredAt":{"type":"string","format":"date-time"},"decisionType":{"type":"string"},"authority":{"type":"string"}}}]},"CommercialCaseTimeline":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommercialCaseTimelineEvent"}}}},"CommercialCaseDecisionRequest":{"type":"object","additionalProperties":false,"required":["decision_type","idempotency_key"],"properties":{"decision_type":{"type":"string","enum":["confirm_link","reject_link","adjust_allocation","approve","hold","dispute","request_evidence","mark_evidence_insufficient","resolve","reopen"]},"reason":{"type":"string","maxLength":10000},"evidence_snapshot":{"type":"object","additionalProperties":true},"previous_state":{"type":"object","additionalProperties":true},"effective_at":{"type":"string","format":"date-time"},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"link_id":{"type":"string","maxLength":100},"allocation_id":{"type":"string","maxLength":100},"amount":{"type":"number"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"operation":{"type":"string","enum":["adjust","reverse"]}}},"CommercialCaseBankingContext":{"type":"object","additionalProperties":false,"required":["contract","version","caseId","caseReference","lifecycleState","compact","railStatus","allocations","evidence","unresolvedConflicts","corrections"],"properties":{"contract":{"const":"commercial-case-banking-ledger-context"},"version":{"const":"1.0.0"},"caseId":{"type":"string"},"caseReference":{"type":"string"},"lifecycleState":{"type":"string"},"compact":{"type":"object"},"railStatus":{"type":"array","items":{"type":"object"}},"allocations":{"type":"array","items":{"$ref":"#/components/schemas/CommercialCaseAllocation"}},"evidence":{"type":"array","items":{"type":"object"}},"unresolvedConflicts":{"type":"integer","minimum":0},"corrections":{"type":"array","items":{"type":"object"}}}},"UnsupportedPprVersion":{"type":"object","additionalProperties":false,"required":["error_code","message","requested_version","supported_versions"],"properties":{"error_code":{"const":"UNSUPPORTED_VERSION"},"message":{"type":"string"},"requested_version":{"type":"string"},"supported_versions":{"type":"array","items":{"const":"1.0.0"}}}},"AirwallexDeliveryRequest":{"type":"object","additionalProperties":false,"required":["commercial_case_id","configuration_id","idempotency_key","target_type","external_id"],"properties":{"commercial_case_id":{"type":"string","minLength":1,"maxLength":100},"configuration_id":{"type":"string","minLength":1,"maxLength":100},"idempotency_key":{"type":"string","minLength":1,"maxLength":255},"target_type":{"type":"string","enum":["payment_intent","transfer"]},"external_id":{"type":"string","minLength":1,"maxLength":500}}},"AirwallexDeliveryConfigurationCreate":{"type":"object","additionalProperties":false,"required":["provider_account_id","environment"],"properties":{"provider_account_id":{"type":"string","minLength":1,"maxLength":200},"environment":{"const":"sandbox"},"enabled":{"type":"boolean","default":false},"enabled_operations":{"type":"array","items":{"type":"string","enum":["payment_intent","transfer","payment_intent_reference","transfer_reference"]},"maxItems":4},"permitted_case_fields":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":100}}},"AirwallexDeliveryConfigurationUpdate":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"enabled":{"type":"boolean"},"enabled_operations":{"type":"array","items":{"type":"string","enum":["payment_intent","transfer","payment_intent_reference","transfer_reference"]},"maxItems":4},"permitted_case_fields":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":100}}},"AirwallexDeliveryConfiguration":{"type":"object","additionalProperties":false,"required":["id","provider_account_id","environment","enabled","validation_status","enabled_operations","permitted_case_fields","updated_at"],"properties":{"id":{"type":"string"},"provider_account_id":{"type":"string"},"environment":{"const":"sandbox"},"enabled":{"type":"boolean"},"validation_status":{"type":"string","enum":["configured_unvalidated","validated","invalid"]},"validated_at":{"type":"string","format":"date-time"},"validation_failure_code":{"type":"string"},"enabled_operations":{"type":"array","items":{"type":"string"}},"permitted_case_fields":{"type":"array","items":{"type":"string"}},"updated_at":{"type":"string","format":"date-time"}}},"AirwallexSuccessorRequest":{"type":"object","additionalProperties":false,"required":["idempotency_key"],"properties":{"idempotency_key":{"type":"string","minLength":1,"maxLength":255}}},"AirwallexDelivery":{"type":"object","additionalProperties":false,"required":["id","status","target_type","external_id","updated_at"],"properties":{"id":{"type":"string"},"status":{"type":"string"},"target_type":{"type":"string","enum":["payment_intent","transfer"]},"external_id":{"type":"string"},"provider_reference":{"type":"string"},"last_error_code":{"type":"string"},"send_started_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ConsumerCommercialCaseGrantRequest":{"type":"object","additionalProperties":false,"required":["recipient_reference","recipient_attribution"],"properties":{"recipient_reference":{"type":"string","minLength":32,"maxLength":500,"description":"Opaque, time-bound portal invite token created by the receiving tenant; never an API-key ID."},"source_account_id":{"type":"string","minLength":1,"maxLength":200},"connector_id":{"type":"string","minLength":1,"maxLength":100},"recipient_attribution":{"type":"string","minLength":1,"maxLength":200},"expires_at":{"type":"string","format":"date-time"}},"anyOf":[{"required":["source_account_id"]},{"required":["connector_id"]}]},"ConsumerCommercialCaseGrant":{"type":"object","additionalProperties":false,"required":["id","operations","recipient_attribution","effective_at","expires_at","revoked_at","created_at"],"properties":{"id":{"type":"string"},"connector_id":{"type":["string","null"]},"operations":{"type":"array","items":{"type":"string"}},"recipient_attribution":{"type":"string"},"effective_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"ConsumerCommercialCaseGrantEnvelope":{"type":"object","additionalProperties":false,"required":["grant"],"properties":{"grant":{"$ref":"#/components/schemas/ConsumerCommercialCaseGrant"}}},"ConsumerCommercialCaseGrantList":{"type":"object","additionalProperties":false,"required":["grants"],"properties":{"grants":{"type":"array","items":{"$ref":"#/components/schemas/ConsumerCommercialCaseGrant"}}}},"Error":{"type":"object","required":["error_code","message"],"properties":{"error_code":{"type":"string","example":"NOT_FOUND"},"message":{"type":"string","example":"Purchase not found"}}},"LineItem":{"type":"object","required":["name","price"],"properties":{"name":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"number"},"category":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"upc":{"type":"string","maxLength":14,"nullable":true},"brand":{"type":"string","nullable":true},"is_fsa_eligible":{"type":"boolean","nullable":true}}},"CreatePurchase":{"type":"object","required":["amount","currency","reference_id","timestamp","status"],"properties":{"amount":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","minLength":1,"maxLength":10,"example":"USD"},"merchant_name":{"type":"string"},"transaction_type":{"type":"string","enum":["transfer","payment","refund","deposit","withdrawal","purchase","auth","pre_auth","capture","void"]},"reference_id":{"type":"string","minLength":1},"timestamp":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["pending","processing","completed","failed","reversed","refunded"]},"memo":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"tax":{"type":"number"},"total":{"type":"number"},"entity_id":{"type":"string"},"signal_type":{"type":"string","enum":["card_transaction","receipt","invoice","email_confirmation","api_submission","mileage_claim","per_diem_claim","mobile_capture","wallet_payment"]},"gl_code":{"type":"string","maxLength":50},"cost_center":{"type":"string","maxLength":100},"department":{"type":"string","maxLength":100},"project_code":{"type":"string","maxLength":100},"rail_source":{"type":"string","enum":["fednow","sepa_instant","upi","swift","iso20022","camt052","camt053","camt054","mt940","mt942","bai2","stripe","coinbase_commerce","hedera","x402","ach","rtp","wire","card","primer","stables","cybrid","rainforest","pingpong","thunes_accept","thunes_mt","adyen","mollie","rapyd","pix","mercado_pago","checkout","klarna","stone","pagseguro","boleto","xmoney_crypto","knot","truelayer","ebizcharge","maxio","orb","chargebee","recurly","paddle","nmi","paystand","authorize_net","edi204","edi210","edi211","edi214","edi_855_ack","edi_856_asn","edi_997_ack","mcleod","mercurygate","turvo","relay_payments","cass","loop","sila","brasilpays","derivative_path","moonpay","roadsync","fleet_check","wex_fleet","fleetcor","ups","fedex","dhl_express","tforce_freight","trimble","sap_tm","magnus_tms","blue_yonder","estes_express","saia","rl_carriers","arcbest","odfl","alvys_tms","rose_rocket","samsara_eld","motive_eld","edi_820_remittance","edi_990_response","edi_824_advice","checkalt","project44","flexport","bank_feed","carrier_invoice_manual","freight_hero","freight_ops_platform","lojistic","shipwell","cybersource","xero","other"]},"fx_rate":{"type":"number"},"fx_base_currency":{"type":"string","maxLength":10},"origin_jurisdiction":{"type":"string","minLength":2,"maxLength":2,"example":"US"},"settlement_jurisdiction":{"type":"string","minLength":2,"maxLength":2},"merchant_tin":{"type":"string","description":"Payer/payee TIN for 1099 aggregation"},"source_correction":{"type":"object","description":"Creates a new, immutable correction Purchase Object rather than rewriting the original. `source_reference` is the stable idempotency identity for that correction.","required":["correction_type","source_reference","link_status","amount_delta"],"properties":{"correction_type":{"type":"string","enum":["credit_note","amendment","refund","reversal"]},"source_reference":{"type":"string","maxLength":100},"original_purchase_id":{"type":"string","description":"Public `pur_vc_` identity of the original purchase when known."},"original_reference_id":{"type":"string"},"link_status":{"type":"string","enum":["linked","needs_review"],"description":"Submitted source link status. The server resolves and persists the authoritative status."},"effective_at":{"type":"string","format":"date-time"},"reason":{"type":"string","maxLength":2000,"nullable":true},"amount_delta":{"type":"number","description":"Non-zero amount delta; required by the public schema."},"source_metadata":{"type":"object","additionalProperties":true}}}}},"Purchase":{"type":"object","properties":{"id":{"type":"string","example":"pur_vc_abc123"},"object":{"type":"string","enum":["purchase"]},"amount":{"type":"number"},"currency":{"type":"string"},"merchant":{"type":"object","properties":{"name":{"type":"string"},"tin":{"type":"string","nullable":true},"lei":{"type":"string","nullable":true,"description":"Legal Entity Identifier (ISO 17442). Maps to Cdtr.Pty.Id.OrgId.LEI in ISO 20022 camt.053/camt.054."},"enigma_id":{"type":"string","nullable":true},"registered_name":{"type":"string","nullable":true}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"status":{"type":"string"},"signal_type":{"type":"string"},"entity_id":{"type":"string","nullable":true},"expense":{"type":"object","nullable":true,"properties":{"gl_code":{"type":"string","nullable":true},"cost_center":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"project_code":{"type":"string","nullable":true},"approval":{"type":"object","properties":{"status":{"type":"string","enum":["pending_review","approved","rejected","reimbursed"],"nullable":true},"approved_by":{"type":"string","nullable":true},"approved_at":{"type":"string","format":"date-time","nullable":true},"rejection_reason":{"type":"string","nullable":true},"reimbursed_at":{"type":"string","format":"date-time","nullable":true}}}}},"commercial":{"type":"object","description":"Commercial AP intelligence — GL code suggestion, cost center mapping, PO match, exception flags, auto-codeability, and 1099 reporting signals. Inline on every purchase object. Rule-based, no async I/O.","properties":{"object":{"type":"string","enum":["commercial_intelligence"]},"gl_code_suggestion":{"type":"object","nullable":true,"properties":{"code":{"type":"string","example":"6400"},"description":{"type":"string","example":"Office Supplies"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"0.0–1.0. 1.0 = caller-provided; 0.92 = merchant name match; 0.70 = category match; 0.45 = item category."},"matched_on":{"type":"string","enum":["caller_provided","merchant_name","category","item_category"]}}},"cost_center_suggestion":{"type":"object","properties":{"value":{"type":"string","nullable":true},"confidence":{"type":"string","enum":["high","medium","low"],"nullable":true},"source":{"type":"string","enum":["caller_provided","department","project_code","absent"]}}},"po_match":{"type":"object","properties":{"status":{"type":"string","enum":["matched","partial","unmatched"]},"confidence":{"type":"number","minimum":0,"maximum":1},"matched_po_reference":{"type":"string","nullable":true,"example":"AP-2026-00831"},"match_source":{"type":"string","enum":["reference_id","invoice_metadata","po_number_field","absent"]}}},"exception_flags":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["missing_po","missing_vendor_tin","duplicate_invoice","missing_line_items","price_variance","quantity_mismatch"]},"description":{"type":"string"},"severity":{"type":"string","enum":["warning","error"]}}}},"auto_codeable":{"type":"boolean","description":"true when GL confidence ≥ 0.70 and no error-severity exceptions. Safe to write GL code directly to ERP without AP review queue."},"reportable_1099":{"type":"boolean","nullable":true,"description":"null when merchant TIN absent. true when amount ≥ $600, TIN present, and not flagged personal. Informational only."},"tax_treatment":{"type":"object","nullable":true,"properties":{"treatment":{"type":"string","enum":["fully_deductible","partially_deductible","capitalized","non_deductible","unknown"]},"basis":{"type":"string"},"category_anchor":{"type":"string","nullable":true},"disclaimer":{"type":"string","example":"Informational only. Not tax advice."}}}}},"unification":{"type":"object","properties":{"confidence":{"type":"number","nullable":true},"signal_count":{"type":"integer","nullable":true}}},"lifecycle":{"type":"object","properties":{"return_eligible":{"type":"boolean"},"warranty_active":{"type":"boolean"},"days_since_purchase":{"type":"integer"}}},"lifecycle_events":{"type":"array","description":"Post-delivery warranty, return, subscription, audit, dispute, and delivery events. This does not replace the existing payment lifecycle chain.","items":{"$ref":"#/components/schemas/PostDeliveryLifecycleEvent"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PurchaseList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Purchase"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"total":{"type":"integer"}}},"Entity":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["entity"]},"external_ids":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"id":{"type":"string"}}}},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"tin":{"type":"string","nullable":true,"description":"Payer TIN for 1099 aggregation"},"kyc_status":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"EntityList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Entity"}},"has_more":{"type":"boolean"}}},"CreateEntity":{"type":"object","properties":{"external_ids":{"type":"array","items":{"type":"object","required":["source","id"],"properties":{"source":{"type":"string"},"id":{"type":"string"}}}},"name":{"type":"string"},"email":{"type":"string","format":"email"},"tin":{"type":"string"},"phone":{"type":"string"}}},"Policy":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["expense_policy"]},"name":{"type":"string"},"rule_type":{"type":"string","enum":["amount_limit","merchant_blocklist","category_blocklist","require_memo","require_gl_code"]},"rule_value":{"type":"string"},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"CreatePolicy":{"type":"object","required":["name","rule_type","rule_value"],"properties":{"name":{"type":"string","maxLength":200},"rule_type":{"type":"string","enum":["amount_limit","merchant_blocklist","category_blocklist","require_memo","require_gl_code"]},"rule_value":{"type":"string","description":"Numeric string for amount_limit; comma-separated names for blocklists; any non-empty string for flag rules"},"enabled":{"type":"boolean","default":true}}},"ReturnEligibility":{"type":"object","properties":{"object":{"type":"string","enum":["return_eligibility"]},"purchase_id":{"type":"string","example":"pur_vc_4fa82e91"},"eligible":{"type":"boolean","description":"Whether the purchase is currently within the merchant's return window"},"days_remaining":{"type":"integer","description":"Calendar days remaining before the return deadline. Zero when not eligible."},"return_deadline":{"type":"string","format":"date","nullable":true,"description":"ISO date (YYYY-MM-DD) by which a return must be initiated"},"return_window_days":{"type":"integer","nullable":true,"description":"The merchant's configured return window in days"},"merchant":{"type":"string","nullable":true},"amount":{"type":"number"},"currency":{"type":"string"},"purchased_at":{"type":"string","format":"date-time"},"warranty":{"type":"object","nullable":true,"properties":{"active":{"type":"boolean"},"expires":{"type":"string","format":"date","nullable":true}}}}},"ReceiptLink":{"type":"object","properties":{"object":{"type":"string","enum":["receipt_link"]},"token":{"type":"string","example":"rl_a8f2c1d9e0b3","description":"Opaque token — not retrievable after creation"},"url":{"type":"string","format":"uri","example":"https://viacle.io/r/rl_a8f2c1d9e0b3"},"purchase_id":{"type":"string"},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"Null when the link was created without an expiry"},"created_at":{"type":"string","format":"date-time"}}},"ExpenseSummaryItem":{"type":"object","properties":{"group_value":{"type":"string","nullable":true,"description":"The value of the group_by dimension (e.g. department name, GL code)"},"total_amount":{"type":"number","description":"Sum of purchase amounts in this group"},"purchase_count":{"type":"integer","description":"Number of purchases in this group"}}},"ApprovalAuditEntry":{"type":"object","properties":{"event_id":{"type":"string"},"purchase_id":{"type":"string"},"event_type":{"type":"string","enum":["purchase.approval_approved","purchase.approval_rejected","purchase.approval_reimbursed"]},"entity_id":{"type":"string","nullable":true},"data":{"type":"object","properties":{"approved_by":{"type":"string","nullable":true},"rejection_reason":{"type":"string","nullable":true}}},"created_at":{"type":"string","format":"date-time"}}},"CreateWidgetSession":{"type":"object","properties":{"entity_id":{"type":"string","maxLength":200,"description":"Scope the session to a specific entity (person or business)"},"partner_name":{"type":"string","maxLength":100,"description":"Displayed in the embed header"},"theme":{"type":"string","enum":["dark","light"],"default":"dark"},"redirect_url":{"type":"string","format":"uri","description":"URL the embed navigates to on close"},"logo_url":{"type":"string","format":"uri"},"accent_color":{"type":"string","pattern":"^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$","example":"#1ED4C8"},"hide_branding":{"type":"boolean","default":false}}},"WidgetSession":{"type":"object","properties":{"session_token":{"type":"string","description":"JWT to pass as the session query param to the hosted link"},"link_url":{"type":"string","format":"uri","description":"Ready-to-use URL for an iframe src or redirect"},"expires_at":{"type":"integer","description":"Unix timestamp when the token expires (30 min from issuance)"},"entity_id":{"type":"string","nullable":true},"partner_name":{"type":"string","nullable":true}}},"WidgetSessionVerify":{"type":"object","properties":{"valid":{"type":"boolean"},"entity_id":{"type":"string","nullable":true},"partner_name":{"type":"string","nullable":true},"theme":{"type":"string","enum":["dark","light"]}}},"PurchaseLifecycleEvent":{"type":"object","properties":{"id":{"type":"string"},"event_type":{"type":"string","description":"e.g. purchase.created, purchase.updated, purchase.delivered, purchase.returned, purchase.refunded, or a custom type"},"data":{"type":"object","description":"Event-specific payload. Shape varies by event_type.","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"PostDeliveryLifecycleEvent":{"type":"object","required":["event_id","object","purchase_id","event_type","data","timestamp"],"properties":{"event_id":{"type":"string"},"object":{"type":"string","enum":["purchase_lifecycle_event"]},"purchase_id":{"type":"string"},"event_type":{"type":"string","enum":["warranty_activated","warranty_expired","return_window_opened","return_window_closed","subscription_renewal","asset_depreciation_posted","audit_referenced","payment_dispute_opened","payment_dispute_resolved","asset_received"]},"data":{"type":"object","additionalProperties":true},"source":{"type":"string","nullable":true},"timestamp":{"type":"string","format":"date-time"}}},"CreatePostDeliveryLifecycleEvent":{"type":"object","required":["event_type"],"properties":{"event_type":{"type":"string","enum":["warranty_activated","warranty_expired","return_window_opened","return_window_closed","subscription_renewal","asset_depreciation_posted","audit_referenced","payment_dispute_opened","payment_dispute_resolved"]},"data":{"type":"object","additionalProperties":true},"source":{"type":"string","minLength":1,"maxLength":100},"idempotency_key":{"type":"string","minLength":1,"maxLength":255,"description":"Stable caller-generated key for deterministic retry. Reusing it with changed event_type, data, source, or supplied timestamp returns 409."}}},"PostDeliveryLifecycleEventList":{"type":"object","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PostDeliveryLifecycleEvent"}},"has_more":{"type":"boolean","enum":[false]}}},"ApRule":{"type":"object","required":["rule_id","object","name","priority","conditions","action","route_to_email","is_active","created_at"],"properties":{"rule_id":{"type":"string"},"object":{"type":"string","enum":["ap_auto_rule"]},"name":{"type":"string","maxLength":200},"priority":{"type":"integer","minimum":0,"maximum":100},"conditions":{"$ref":"#/components/schemas/ApRuleConditions"},"action":{"type":"string","enum":["auto_approve","route_to"]},"route_to_email":{"type":"string","format":"email","nullable":true},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"ApRuleConditions":{"type":"object","properties":{"amount_min":{"type":"number","minimum":0},"amount_max":{"type":"number","minimum":0},"vendor_trust_min":{"type":"number","minimum":0,"maximum":1},"fraud_flags":{"type":"string","enum":["none"]},"gl_code_required":{"type":"boolean"},"cost_center_required":{"type":"boolean"},"po_required":{"type":"boolean"},"po_match_status":{"type":"string","maxLength":50}},"additionalProperties":false},"CreateApRule":{"type":"object","required":["name","conditions","action"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"priority":{"type":"integer","minimum":0,"maximum":100,"default":0},"conditions":{"$ref":"#/components/schemas/ApRuleConditions"},"action":{"type":"string","enum":["auto_approve","route_to"]},"route_to_email":{"type":"string","format":"email","maxLength":320},"is_active":{"type":"boolean","default":true}}},"UpdateApRule":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"priority":{"type":"integer","minimum":0,"maximum":100},"conditions":{"$ref":"#/components/schemas/ApRuleConditions"},"action":{"type":"string","enum":["auto_approve","route_to"]},"route_to_email":{"type":"string","format":"email","maxLength":320},"is_active":{"type":"boolean"}}},"ApEvaluation":{"type":"object","required":["object","purchase_id","action","rule_id","rule_name","route_to_email","vendor_trust_score","skip_reasons","auto_posted","external_url","target"],"properties":{"object":{"type":"string","enum":["ap_evaluation"]},"purchase_id":{"type":"string"},"action":{"type":"string","enum":["auto_approve","route_to","no_rule"]},"rule_id":{"type":"string","nullable":true},"rule_name":{"type":"string","nullable":true},"route_to_email":{"type":"string","format":"email","nullable":true},"vendor_trust_score":{"type":"number","minimum":0,"maximum":1},"skip_reasons":{"type":"array","items":{"type":"string"}},"auto_posted":{"type":"boolean"},"external_url":{"type":"string","format":"uri","nullable":true},"target":{"type":"string","nullable":true}}},"PurchaseSplit":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string","nullable":true,"description":"Human-readable label for this portion (e.g. 'Marketing Q3')"},"cost_center":{"type":"string","nullable":true},"entity_id":{"type":"string","nullable":true},"amount":{"type":"number","description":"Amount allocated to this split leg"},"percentage":{"type":"number","nullable":true,"description":"Optional percentage for display. Must sum to 100 when provided."},"memo":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"PurchaseSplitsResponse":{"type":"object","properties":{"object":{"type":"string","enum":["purchase_splits"]},"purchase_id":{"type":"string"},"split_count":{"type":"integer"},"splits":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseSplit"}}}},"CreateSplitsBody":{"type":"object","required":["splits"],"properties":{"splits":{"type":"array","minItems":1,"description":"Split legs. Amounts must sum to the purchase total (±0.02 tolerance).","items":{"type":"object","required":["amount"],"properties":{"label":{"type":"string","maxLength":200},"cost_center":{"type":"string","maxLength":100},"entity_id":{"type":"string","maxLength":200},"amount":{"type":"number","exclusiveMinimum":0},"percentage":{"type":"number","minimum":0,"maximum":100},"memo":{"type":"string","maxLength":2000}}}}}},"JournalEntryDraft":{"type":"object","required":["object","id","purchase_id","status","debit_account","credit_account","amount","currency","period","entity","tax_amount","confidence_score","reasoning","erp_journal_entry_id","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["journal_entry_draft"]},"id":{"type":"string","description":"Draft ID (je_…)"},"purchase_id":{"type":"string","description":"Public purchase ID this draft belongs to"},"status":{"type":"string","enum":["draft","posting","posted"],"description":"`draft` — generated but not posted. `posting` — an ERP posting attempt owns the lease. `posted` — posted to ERP."},"debit_account":{"type":"string","nullable":true,"description":"GL account name or code to debit (expense side). Sourced from the purchase GL code; configure via PATCH."},"credit_account":{"type":"string","nullable":true,"description":"GL account name or code to credit. `null` on generation — must be set via PATCH before posting."},"amount":{"type":"number","nullable":true,"description":"Purchase total in the native currency."},"currency":{"type":"string","nullable":true,"description":"ISO 4217 currency code."},"period":{"type":"string","nullable":true,"description":"Accounting period (YYYY-MM)."},"entity":{"type":"string","nullable":true,"description":"Cost center or business entity."},"tax_amount":{"type":"number","nullable":true,"description":"Tax portion of the purchase amount."},"confidence_score":{"type":"number","nullable":true,"description":"0–1 float. Below 0.75 = at least one weak signal."},"reasoning":{"type":"string","nullable":true,"description":"Human-readable explanation of the confidence score."},"erp_journal_entry_id":{"type":"string","nullable":true,"description":"ERP-issued JE ID recorded after posting."},"auto_posted":{"type":"boolean","description":"Present on PATCH responses; true when approval plus configured accounts triggered ERP posting."},"external_url":{"type":"string","format":"uri","nullable":true,"description":"Present on PATCH responses when the posting target returns a record URL."},"target":{"type":"string","nullable":true,"description":"Present on PATCH responses; connector used for automatic posting."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CloseReadinessBreakdown":{"type":"object","required":["missing_gl","missing_cost_center","duplicate_flag","fraud_flag","pending_status"],"properties":{"missing_gl":{"type":"integer","minimum":0},"missing_cost_center":{"type":"integer","minimum":0},"duplicate_flag":{"type":"integer","minimum":0},"fraud_flag":{"type":"integer","minimum":0},"pending_status":{"type":"integer","minimum":0}}},"CloseReadinessException":{"type":"object","required":["purchase_id","missing_fields"],"properties":{"purchase_id":{"type":"string"},"missing_fields":{"type":"array","items":{"type":"string","enum":["gl_code","cost_center","duplicate_flag","fraud_flag","pending_status"]}}}},"CloseReadinessBenchmark":{"type":"object","required":["tier","message"],"properties":{"tier":{"type":"string","enum":["excellent","strong","improving","developing","early"]},"message":{"type":"string"}}},"ReceiptComplianceSummary":{"type":"object","required":["object","group_by","date_from","date_to","overall_compliance_rate_pct","total_purchases","compliant_count","non_compliant_count","groups","generated_at"],"properties":{"object":{"type":"string","enum":["receipt_compliance_summary"]},"group_by":{"type":"string","enum":["entity_id","department","cost_center"]},"date_from":{"type":"string","format":"date","nullable":true},"date_to":{"type":"string","format":"date","nullable":true},"overall_compliance_rate_pct":{"type":"number","minimum":0,"maximum":100},"total_purchases":{"type":"integer","minimum":0},"compliant_count":{"type":"integer","minimum":0},"non_compliant_count":{"type":"integer","minimum":0},"groups":{"type":"array","items":{"$ref":"#/components/schemas/ReceiptComplianceGroup"}},"generated_at":{"type":"integer","description":"Unix timestamp in seconds"}}},"ReceiptComplianceGroup":{"type":"object","required":["group","total_purchases","compliant_count","non_compliant_count","compliance_rate_pct"],"properties":{"group":{"type":"string"},"total_purchases":{"type":"integer","minimum":0},"compliant_count":{"type":"integer","minimum":0},"non_compliant_count":{"type":"integer","minimum":0},"compliance_rate_pct":{"type":"number","minimum":0,"maximum":100}}},"SpendingByTagSummary":{"type":"object","required":["object","date_from","date_to","tag_count","tags","generated_at"],"properties":{"object":{"type":"string","enum":["spending_by_tag"]},"date_from":{"type":"string","format":"date","nullable":true},"date_to":{"type":"string","format":"date","nullable":true},"tag_count":{"type":"integer","minimum":0},"tags":{"type":"array","items":{"$ref":"#/components/schemas/SpendingTag"}},"generated_at":{"type":"integer","description":"Unix timestamp in seconds"}}},"SpendingTag":{"type":"object","required":["tag","total_spend","purchase_count","top_merchants"],"properties":{"tag":{"type":"string"},"total_spend":{"type":"number"},"purchase_count":{"type":"integer","minimum":0},"top_merchants":{"type":"array","items":{"type":"string"}}}},"PaymentRailsSummary":{"type":"object","required":["object","entity_id","date_from","date_to","total_rails","rails","generated_at"],"properties":{"object":{"type":"string","enum":["payment_rails_breakdown"]},"entity_id":{"type":"string","nullable":true},"date_from":{"type":"string","format":"date","nullable":true},"date_to":{"type":"string","format":"date","nullable":true},"total_rails":{"type":"integer","minimum":0},"rails":{"type":"array","items":{"$ref":"#/components/schemas/PaymentRailBreakdown"}},"generated_at":{"type":"integer","description":"Unix timestamp in seconds"}}},"PaymentRailBreakdown":{"type":"object","required":["rail_source","purchase_count","total_spend","spend_percentage"],"properties":{"rail_source":{"type":"string"},"purchase_count":{"type":"integer","minimum":0},"total_spend":{"type":"number"},"spend_percentage":{"type":"number","minimum":0,"maximum":100}}},"VendorConcentrationSummary":{"type":"object","required":["object","entity_id","date_from","date_to","limit","vendors","generated_at"],"properties":{"object":{"type":"string","enum":["vendor_concentration_summary"]},"entity_id":{"type":"string","nullable":true},"date_from":{"type":"string","format":"date","nullable":true},"date_to":{"type":"string","format":"date","nullable":true},"limit":{"type":"integer","minimum":1},"vendors":{"type":"array","items":{"$ref":"#/components/schemas/VendorConcentration"}},"generated_at":{"type":"integer","description":"Unix timestamp in seconds"}}},"VendorConcentration":{"type":"object","required":["merchantId","merchantName","totalSpend","count","spendPercentage"],"properties":{"merchantId":{"type":"string","nullable":true},"merchantName":{"type":"string"},"totalSpend":{"type":"number"},"count":{"type":"integer","minimum":0},"spendPercentage":{"type":"number","minimum":0,"maximum":100}}},"ReconciliationItem":{"type":"object","required":["id","vendor","amount","currency","date","source"],"properties":{"id":{"type":"string"},"vendor":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"date":{"type":"string","format":"date-time","nullable":true},"source":{"type":"string","nullable":true},"canonical_id":{"type":"string"},"confidence":{"type":"number"},"matched_on":{"type":"array","items":{"type":"string"}}}},"ReconciliationStats":{"type":"object","required":["matched","suggested","unmatched","total"],"properties":{"matched":{"type":"integer"},"suggested":{"type":"integer"},"unmatched":{"type":"integer"},"total":{"type":"integer"}}},"Dispute":{"type":"object","properties":{"id":{"type":"string"},"purchase_id":{"type":"string"},"reason":{"type":"string","description":"Free-text description of the dispute"},"reason_code":{"type":"string","nullable":true,"description":"Structured reason code (freight disputes only)"},"freight_detail":{"type":"string","nullable":true,"description":"Additional freight dispute context"},"disputed_amount":{"type":"number","nullable":true,"description":"Amount being disputed. Defaults to the full purchase amount."},"dispute_type":{"type":"string","enum":["freight","billing"]},"status":{"type":"string","enum":["open","pending_correction","resolved","rejected","withdrawn"]},"merchant_response":{"type":"string","nullable":true},"correction_purchase_id":{"type":"string","nullable":true,"description":"Public ID of the corrected purchase, if a correction was issued"},"resolved_at":{"type":"integer","nullable":true,"description":"Unix timestamp when the dispute was resolved, rejected, or withdrawn"},"created_at":{"type":"integer","description":"Unix timestamp"},"updated_at":{"type":"integer","description":"Unix timestamp"}}},"CreateDisputeBody":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Description of the discrepancy or issue"},"disputed_amount":{"type":"number","exclusiveMinimum":0,"description":"Partial amount in dispute. Omit to dispute the full purchase amount."},"freight_reason_code":{"type":"string","enum":["weight_discrepancy","unauthorized_accessorial","rate_mismatch","duplicate_billing","late_delivery","missing_pod","class_reclassification","routing_violation","fuel_surcharge_discrepancy","detention_overcharge","damage_claim","shortage"],"description":"Structured freight dispute code. Providing this sets dispute_type to 'freight'."},"freight_detail":{"type":"string","maxLength":2000,"description":"Additional detail for freight disputes (e.g. BOL number, expected vs actual weight)"}}},"UpdateDisputeBody":{"type":"object","properties":{"status":{"type":"string","enum":["pending_correction","resolved","rejected","withdrawn"]},"merchant_response":{"type":"string","maxLength":2000,"nullable":true,"description":"Merchant or carrier response to record"},"correction_purchase_id":{"type":"string","description":"Public ID of a correction purchase issued to settle the dispute"}}},"CommercialEventIngest":{"type":"object","required":["source","record"],"properties":{"commercial_event_id":{"type":"string","description":"Existing event ID. Omit to create; supply to attach later source facts to the same event."},"source":{"type":"object","required":["connector_type","external_event_id"],"properties":{"connector_type":{"type":"string","example":"bank_ach"},"external_event_id":{"type":"string","example":"ach_20260826_0001"},"occurred_at":{"type":"string","format":"date-time"},"source_role":{"type":"string","enum":["invoice","credit_note","bank_transaction","payment","receipt","purchase_order","shipment","contract","other","unknown"],"description":"The commercial role of this source assertion. Omit only for legacy sources; the server retains an explicit value when supplied and otherwise classifies conservatively."},"assertion_kind":{"type":"string","enum":["source_asserted","deterministic_projection","inferred","human_decision","legacy_observed"],"description":"How the assertion was produced. Source ingestion normally uses source_asserted."},"metadata":{"type":"object","additionalProperties":true,"description":"Attributable source and evidence metadata. Supported conventional keys include `source_system`, `evidence_type`, `evidence_uri`, `captured_at`, and `content_digest`; unknown metadata is retained with the source assertion.","example":{"source_system":"Acme ERP","evidence_type":"invoice","evidence_uri":"sandbox://invoices/INV-1001","captured_at":"2026-09-06T10:00:00Z","content_digest":"sha256:...","rail_source":"ach","purchase_source":"bank_feed"}}}},"record":{"type":"object","description":"Normalized transaction, invoice, order, or supporting document fields. A new event requires `merchant_name` and `amount`; incremental evidence may contain only the additional fields.","properties":{"merchant_name":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string","example":"USD"},"reference_id":{"type":"string"},"invoice_number":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number"},"quantity":{"type":"number"}}}}}}}},"CommercialEventRelationshipDecision":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["confirm","reject"]},"reason":{"type":"string","maxLength":2000}}},"CommercialEventRelationshipProposal":{"type":"object","additionalProperties":false,"required":["source_type","source_id","amount","currency","observed_at"],"properties":{"source_type":{"type":"string","minLength":1,"maxLength":40,"example":"payment_record"},"source_id":{"type":"string","minLength":1,"maxLength":200,"description":"Stable identity in the named payment source."},"amount":{"type":"number"},"currency":{"type":"string","minLength":3,"maxLength":10,"example":"USD"},"observed_at":{"type":"string","format":"date-time"},"payment_reference":{"type":"string","maxLength":200},"merchant_name":{"type":"string","maxLength":500},"source_snapshot":{"type":"object","additionalProperties":true,"description":"Immutable, caller-supplied payment observation details."}},"anyOf":[{"required":["payment_reference"]},{"required":["merchant_name"]},{"required":["source_snapshot"]}]},"CommercialEventRelationship":{"type":"object","required":["object","commercial_event_id","id","relationship_type","status","confidence","rationale","matched_fields","source","target_purchase_id"],"properties":{"object":{"const":"commercial_event_relationship"},"commercial_event_id":{"type":"string"},"id":{"type":"string"},"relationship_type":{"type":"string","example":"payment"},"status":{"type":"string","enum":["proposed","ambiguous","confirmed","rejected","superseded"]},"confidence":{"type":"number","minimum":0,"maximum":1},"rationale":{"type":"string"},"matched_fields":{"type":"array","items":{"type":"string"}},"source":{"type":"object"},"target_purchase_id":{"type":"string"},"target_snapshot":{"type":"object","nullable":true},"amount":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"created_at":{"type":"integer","nullable":true},"updated_at":{"type":"integer","nullable":true}}},"CommercialEvent":{"type":"object","required":["object","api_version","id","state","context","source_records","evidence","relationships","corrections","history"],"properties":{"object":{"type":"string","enum":["commercial_event"]},"api_version":{"type":"string","example":"2026-08-26"},"id":{"type":"string","description":"Stable public event identity"},"purchase_id":{"type":"string","description":"Backward-compatible Purchase Object identity"},"compatibility_purchase_url":{"type":"string"},"state":{"type":"object","properties":{"resolution_status":{"type":"string","enum":["resolved","unresolved","conflicting"]},"has_unresolved_conflicts":{"type":"boolean"},"pending_relationship_count":{"type":"integer","description":"Suggested relationships awaiting an explicit confirmation or rejection"},"source_count":{"type":"integer"},"evidence_count":{"type":"integer"}}},"context":{"type":"object","required":["evidence_status","decision_status","confidence","risk_flags","recommended_action","owner","relationship_resolution","outcome_status","lifecycle_history","audit_history"],"properties":{"evidence_status":{"type":"string","enum":["complete","gaps","conflicts","unreviewed"]},"decision_status":{},"confidence":{"type":"number","nullable":true},"risk_flags":{"type":"array","items":{"type":"object"}},"recommended_action":{"type":"string"},"owner":{"nullable":true},"relationship_resolution":{"type":"object"},"outcome_status":{"nullable":true},"lifecycle_history":{"type":"array","items":{"type":"object"}},"audit_history":{"type":"array","items":{"type":"object"}}}},"source_records":{"type":"array","items":{"type":"object","required":["id","connector_type","event_type","source_role","assertion_kind"],"properties":{"id":{"type":"string"},"connector_type":{"type":"string"},"event_type":{"type":"string"},"source_role":{"type":"string","enum":["invoice","credit_note","bank_transaction","payment","receipt","purchase_order","shipment","contract","other","unknown"]},"assertion_kind":{"type":"string","enum":["source_asserted","deterministic_projection","inferred","human_decision","legacy_observed"]},"external_event_id":{"type":"string","nullable":true},"source_version":{"type":"string","nullable":true},"payload_hash":{"type":"string"},"occurred_at":{"type":"integer","nullable":true},"received_at":{"type":"integer","nullable":true},"metadata":{"type":"object"}}}},"projection":{"type":"object","nullable":true,"description":"Latest deterministic projection. Each provenance entry identifies source_role, assertion_kind, source_signal_id, optional source_event_id, field_path, numeric authority, and role-bearing alternate_sources when values conflict."},"evidence":{"type":"array","items":{"type":"object","required":["id","connector_type","source_format","source_role","assertion_kind"],"properties":{"id":{"type":"string"},"source_event_id":{"type":"string","nullable":true},"connector_type":{"type":"string"},"source_format":{"type":"string"},"source_role":{"type":"string","enum":["invoice","credit_note","bank_transaction","payment","receipt","purchase_order","shipment","contract","other","unknown"]},"assertion_kind":{"type":"string","enum":["source_asserted","deterministic_projection","inferred","human_decision","legacy_observed"]},"payload_hash":{"type":"string"},"payload_ref":{"type":"string","nullable":true},"parser_version":{"type":"string"},"identifiers":{"type":"array"},"references":{"type":"array"},"occurred_at":{"type":"integer","nullable":true},"received_at":{"type":"integer","nullable":true},"retention_expires_at":{"type":"integer","nullable":true}}}},"relationships":{"type":"array","items":{"type":"object"}},"conflicts":{"type":"object"},"corrections":{"type":"array","items":{"type":"object"}},"history":{"type":"array","items":{"type":"object"}}}},"CommercialEventShared":{"type":"object","description":"Section-filtered Commercial Event returned to an authorized recipient. Identity/version fields are always present; every other section requires an explicit grant.","required":["object","api_version","id","purchase_id","shared_access"],"properties":{"object":{"type":"string","enum":["commercial_event"]},"api_version":{"type":"string"},"id":{"type":"string"},"purchase_id":{"type":"string"},"shared_access":{"type":"object","required":["grant_id","allowed_sections"],"properties":{"grant_id":{"type":"string"},"allowed_sections":{"type":"array","items":{"$ref":"#/components/schemas/CommercialEventSection"}}}},"context":{"type":"object"},"source_records":{"type":"array","items":{"type":"object"}},"projection":{"type":"object","nullable":true},"evidence":{"type":"array","items":{"type":"object"}},"relationships":{"type":"array","items":{"type":"object"}},"conflicts":{"type":"object"},"corrections":{"type":"array","items":{"type":"object"}},"history":{"type":"array","items":{"type":"object"}}}},"CommercialEventOperationScope":{"type":"string","enum":["commercial_event:read","commercial_event:publish","commercial_event:append"]},"CommercialEventSection":{"type":"string","enum":["context","source_records","projection","evidence","relationships","conflicts","corrections","history"]},"CommercialEventShareRequest":{"type":"object","additionalProperties":false,"required":["granted_to_key_id","scopes","sections"],"properties":{"granted_to_key_id":{"type":"string","description":"Active recipient API key ID"},"scopes":{"type":"array","minItems":1,"uniqueItems":true,"items":{"$ref":"#/components/schemas/CommercialEventOperationScope"}},"sections":{"type":"array","minItems":1,"uniqueItems":true,"items":{"$ref":"#/components/schemas/CommercialEventSection"}},"expires_at":{"type":"string","format":"date-time","description":"Optional future expiry"}}},"CommercialEventShare":{"type":"object","required":["object","id","resource","granted_to_key_id","operation_scopes","sections","status","created_at"],"properties":{"object":{"const":"commercial_event_share"},"id":{"type":"string"},"resource":{"type":"string","pattern":"^commercial_event:"},"granted_to_key_id":{"type":"string"},"operation_scopes":{"type":"array","items":{"$ref":"#/components/schemas/CommercialEventOperationScope"}},"sections":{"type":"array","items":{"$ref":"#/components/schemas/CommercialEventSection"}},"expires_at":{"type":["string","null"],"format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["active","expired","revoked"]},"created_at":{"type":"integer"}}},"PortablePurchaseEnvelope":{"type":"object","additionalProperties":false,"required":["standard","profile","version","record"],"properties":{"standard":{"const":"portable-purchase-record"},"profile":{"const":"core"},"version":{"const":"1.0.0"},"record":{"$ref":"#/components/schemas/PortablePurchaseRecord"},"extensions":{"$ref":"#/components/schemas/PortablePurchaseExtensions"}}},"PortablePurchaseRecord":{"type":"object","additionalProperties":false,"required":["id","purchasedAt","status","total","participants","sources","provenance"],"properties":{"id":{"type":"string"},"purchasedAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["pending","completed","cancelled","refunded","partially_refunded"]},"total":{"$ref":"#/components/schemas/PortablePurchaseMoney"},"participants":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/PortablePurchaseParticipant"}},"sources":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/PortablePurchaseSource"}},"evidence":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/PortablePurchaseEvidence"}},"references":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/PortablePurchaseReference"}},"items":{"type":"array","maxItems":10000,"items":{"$ref":"#/components/schemas/PortablePurchaseItem"}},"provenance":{"$ref":"#/components/schemas/PortablePurchaseProvenance"},"extensions":{"$ref":"#/components/schemas/PortablePurchaseExtensions"}}},"PortablePurchaseMoney":{"type":"object","additionalProperties":false,"required":["amount","currency"],"properties":{"amount":{"type":"number"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}}},"PortablePurchaseIdentifier":{"type":"object","additionalProperties":false,"required":["scheme","value"],"properties":{"scheme":{"type":"string","minLength":1,"maxLength":100},"value":{"type":"string","minLength":1,"maxLength":500}}},"PortablePurchaseDigest":{"type":"object","additionalProperties":false,"required":["algorithm","value"],"properties":{"algorithm":{"type":"string","minLength":1,"maxLength":100},"value":{"type":"string","minLength":1,"maxLength":1000}}},"PortablePurchaseParticipant":{"type":"object","additionalProperties":false,"required":["id","role"],"properties":{"id":{"type":"string","minLength":1,"maxLength":200},"role":{"type":"string","enum":["merchant","processor","bank","erp","enterprise","publisher","consumer"]},"name":{"type":"string","minLength":1,"maxLength":500},"identifiers":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/PortablePurchaseIdentifier"}},"extensions":{"$ref":"#/components/schemas/PortablePurchaseExtensions"}}},"PortablePurchaseReference":{"type":"object","additionalProperties":false,"required":["type","value"],"properties":{"type":{"type":"string","minLength":1,"maxLength":100},"value":{"type":"string","minLength":1,"maxLength":500},"issuer":{"type":"string","minLength":1,"maxLength":200},"url":{"type":"string","format":"uri","maxLength":2000},"extensions":{"$ref":"#/components/schemas/PortablePurchaseExtensions"}}},"PortablePurchaseSource":{"type":"object","additionalProperties":false,"required":["id","type","receivedAt"],"description":"Must include externalId or payloadDigest. participantId must reference a record participant.","anyOf":[{"required":["externalId"]},{"required":["payloadDigest"]}],"properties":{"id":{"type":"string","minLength":1,"maxLength":200},"type":{"type":"string","enum":["merchant","processor","bank","erp","enterprise","publisher","consumer","other"]},"occurredAt":{"type":"string","format":"date-time"},"receivedAt":{"type":"string","format":"date-time"},"participantId":{"type":"string","minLength":1,"maxLength":200},"externalId":{"type":"string","minLength":1,"maxLength":500},"payloadDigest":{"$ref":"#/components/schemas/PortablePurchaseDigest"},"extensions":{"$ref":"#/components/schemas/PortablePurchaseExtensions"}}},"PortablePurchaseEvidence":{"type":"object","additionalProperties":false,"required":["id","type","capturedAt"],"description":"sourceId, when present, must reference a record source.","properties":{"id":{"type":"string","minLength":1,"maxLength":200},"type":{"type":"string","enum":["receipt","invoice","payment_confirmation","statement","order","delivery","other"]},"capturedAt":{"type":"string","format":"date-time"},"uri":{"type":"string","format":"uri","maxLength":2000},"digest":{"$ref":"#/components/schemas/PortablePurchaseDigest"},"sourceId":{"type":"string","minLength":1,"maxLength":200},"extensions":{"$ref":"#/components/schemas/PortablePurchaseExtensions"}}},"PortablePurchaseItem":{"type":"object","additionalProperties":false,"required":["description"],"properties":{"id":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","minLength":1,"maxLength":2000},"quantity":{"type":"number","exclusiveMinimum":0,"default":1},"unitPrice":{"$ref":"#/components/schemas/PortablePurchaseMoney"},"total":{"$ref":"#/components/schemas/PortablePurchaseMoney"},"references":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/PortablePurchaseReference"}},"extensions":{"$ref":"#/components/schemas/PortablePurchaseExtensions"}}},"PortablePurchaseProvenance":{"type":"object","additionalProperties":false,"required":["createdAt","assertedBy","sourceIds"],"description":"assertedBy must reference a participant; every sourceIds entry must reference a record source.","properties":{"createdAt":{"type":"string","format":"date-time"},"assertedBy":{"type":"string","minLength":1,"maxLength":200},"sourceIds":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1,"maxLength":200}},"transformation":{"type":"string","minLength":1,"maxLength":500},"extensions":{"$ref":"#/components/schemas/PortablePurchaseExtensions"}}},"PortablePurchaseExtensions":{"type":"object","description":"Additive extension map. Every key must be vendor-namespaced, such as com.example.fulfillment.","propertyNames":{"pattern":"^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$"},"additionalProperties":true},"CommercialEventContextAppend":{"type":"object","additionalProperties":false,"required":["idempotency_key","actor","source","timestamp","reason","status"],"properties":{"idempotency_key":{"type":"string","maxLength":255},"actor":{"type":"string"},"source":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"evidence_references":{"type":"array","items":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string"},"id":{"type":"string"}}}},"reason":{"type":"string"},"status":{"type":"string"},"metadata":{"type":"object"}}}}}}