{"data":{"openapi":"3.1.0","info":{"title":"FiscalVault Nexus API","version":"0.1.0","description":"FiscalVault Nexus is the shared platform/API layer for the FiscalVault\necosystem (Business Workspace, Accountant Workspace, Admin/Operations,\nFlutter Mobile, future integrations). All application-facing endpoints\nare versioned under /api/v1.\n\nConventions:\n- Every response uses the standard envelope { data, meta } or { error }.\n- Every response carries X-Request-Id; supply it (or X-Correlation-Id)\n  to correlate with your own logs.\n- Authentication: Authorization: Bearer <managed access token> issued\n  by the existing FiscalVault authentication system.\n- Tenant context is resolved server-side from the authenticated\n  principal's real memberships. X-Organization-Id selects among the\n  principal's memberships and is never trusted blindly.\n- List endpoints use cursor pagination (cursor, limit, sort).\n- Mutation endpoints accept Idempotency-Key for safe retries.\n- CORS is allowlist-based per deployment; there is no wildcard origin.\n- Uploads are direct-to-storage: Nexus authorizes a signed destination\n  and the client PUTs bytes to object storage; bytes never pass\n  through the API."},"servers":[{"url":"/api/public/v1","description":"Browser-reachable API surface. Identical routing and identical authentication to /api/v1; only the hosting access gate differs."},{"url":"/api/v1","description":"API v1 (server-to-server)"}],"tags":[{"name":"Platform"},{"name":"Identity"},{"name":"Organizations"},{"name":"Documents"},{"name":"Accounting"},{"name":"Accounting Office"},{"name":"Uploads"}],"components":{"schemas":{"AccountingOfficeContext":{"type":"object","description":"Server-resolved Accounting Office context for the caller (Milestone 1). State machine: NO_OFFICE (no memberships) · ACTIVE (exactly one active membership — the only state carrying an officeId) · MEMBERSHIP_DISABLED (memberships exist but none is active) · MULTIPLE_OFFICES (more than one active membership; M1 supports a single office context and never selects one arbitrarily).","required":["state"],"properties":{"state":{"type":"string","enum":["NO_OFFICE","ACTIVE","MEMBERSHIP_DISABLED","MULTIPLE_OFFICES"]},"officeId":{"type":"string","description":"Present only when state is ACTIVE."},"role":{"type":"string","enum":["OWNER","ADMIN","ACCOUNTANT","REVIEWER","VIEWER"],"description":"Office-scoped role; present only when state is ACTIVE."},"capabilities":{"type":"array","items":{"type":"string","enum":["office.read","office.manage"]},"description":"Server-resolved foundation capabilities (not the final permission matrix); present only when state is ACTIVE."},"office":{"type":["object","null"],"description":"Office snapshot; present only when state is ACTIVE.","properties":{"legalName":{"type":"string"},"tradingName":{"type":"string"},"countryCode":{"type":"string","example":"PT"},"verificationStatus":{"type":"string","enum":["unverified","pending","verified","rejected","expired"]},"publicationStatus":{"type":"string","enum":["draft","review","published","unpublished"]}}},"membershipCount":{"type":"integer","description":"Present for MEMBERSHIP_DISABLED and MULTIPLE_OFFICES."}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Managed access token issued by the existing FiscalVault authentication system. Nexus verifies it and resolves organization memberships through the FiscalVault Platform API (/me), and forwards the token verbatim on every upstream call. Nexus never connects to the FiscalVault database or storage directly. Local development only: an explicit opt-in dev-header resolver (X-FV-User-Id, X-FV-Role, X-FV-Organizations) can stand in for this scheme; it is forbidden in production."}},"parameters":{"OrganizationHeader":{"name":"X-Organization-Id","in":"header","required":false,"description":"Selects the active organization among the principal's memberships. Defaults to the first membership. Non-memberships are rejected (403).","schema":{"type":"string"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"8-128 character key. Retries with the same key replay the first response.","schema":{"type":"string","minLength":8,"maxLength":128}},"Cursor":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous page's meta.nextCursor.","schema":{"type":"string"}},"Limit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"PeriodPath":{"name":"period","in":"path","required":true,"description":"Accounting period in \"YYYY-MM\" format.","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}}}},"paths":{"/health":{"get":{"tags":["Platform"],"operationId":"getHealth","summary":"Platform/API health (no deep dependency audit)","security":[],"responses":{"200":{"description":"Platform health","headers":{"X-Request-Id":{"description":"Correlation/request ID for support and log lookup.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["status","service","apiVersion","serviceVersion","time"],"description":"Minimal public health. Exposes no tenant, database, storage, provider or infrastructure information.","properties":{"status":{"type":"string","enum":["ok","degraded"]},"service":{"type":"string","enum":["fiscalvault-nexus"]},"apiVersion":{"type":"string","enum":["v1"]},"serviceVersion":{"type":"string"},"time":{"type":"string","format":"date-time"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation/request ID echoed for every request."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page (list endpoints only)."}},"additionalProperties":true}}}}}}}}},"/me":{"get":{"tags":["Identity"],"operationId":"getCurrentPrincipal","summary":"Normalized authenticated principal/context","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/OrganizationHeader"}],"responses":{"200":{"description":"Current principal","headers":{"X-Request-Id":{"description":"Correlation/request ID for support and log lookup.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["userId","role","scopes","organizationIds","authMethod","activeOrganizationId","productAccess","accountingOffice"],"properties":{"userId":{"type":"string"},"role":{"type":"string","enum":["OWNER","MANAGER","ACCOUNTANT","VIEWER","ADMIN_OPERATIONS","SERVICE"]},"scopes":{"type":"array","items":{"type":"string"}},"organizationIds":{"type":"array","items":{"type":"string"}},"authMethod":{"type":"string","enum":["DEV_HEADERS","BEARER"]},"activeOrganizationId":{"type":["string","null"]},"productAccess":{"type":"object","description":"Server-resolved product access. Authentication and product access are separate authorities: a valid identity alone yields NONE. Unknown products/statuses never appear here.","required":["accountantWorkspace"],"properties":{"accountantWorkspace":{"type":"object","required":["state"],"properties":{"state":{"type":"string","enum":["NONE","ACTIVE","DISABLED"]}}}}},"accountingOffice":{"$ref":"#/components/schemas/AccountingOfficeContext"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation/request ID echoed for every request."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page (list endpoints only)."}},"additionalProperties":true}}}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden (scope or tenant access)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"502":{"description":"FiscalVault Platform API response contract violation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"503":{"description":"FiscalVault Platform API unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}}}}},"/organization":{"get":{"tags":["Organizations"],"operationId":"getActiveOrganization","summary":"Active authorized organization (server-resolved tenant)","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/OrganizationHeader"}],"responses":{"200":{"description":"Active organization","headers":{"X-Request-Id":{"description":"Correlation/request ID for support and log lookup.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","name","country","businessProfiles"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":["string","null"],"example":"PT"},"businessProfiles":{"type":"array","description":"Business profiles belonging to this tenant; documents and periods aggregate across them.","items":{"type":"object","required":["id","name","legalName","country"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"legalName":{"type":["string","null"]},"country":{"type":["string","null"]}}}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation/request ID echoed for every request."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page (list endpoints only)."}},"additionalProperties":true}}}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden (scope or tenant access)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"502":{"description":"FiscalVault Platform API response contract violation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"503":{"description":"FiscalVault Platform API unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}}}}},"/documents":{"get":{"tags":["Documents"],"operationId":"listDocuments","summary":"List documents for the active organization","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/OrganizationHeader"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["-createdAt"],"default":"-createdAt"}}],"responses":{"200":{"description":"Page of documents across the tenant's business profiles, merged in createdAt-descending order","headers":{"X-Request-Id":{"description":"Correlation/request ID for support and log lookup.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","businessProfileId","reference","status","category","createdAt","updatedAt"],"properties":{"id":{"type":"string"},"businessProfileId":{"type":"string","description":"Business profile (within the tenant) owning this document."},"reference":{"type":["string","null"]},"status":{"type":["string","null"],"description":"Lifecycle status owned by the platform domain."},"category":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation/request ID echoed for every request."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page (list endpoints only)."}},"additionalProperties":true}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden (scope or tenant access)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"502":{"description":"FiscalVault Platform API response contract violation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"503":{"description":"FiscalVault Platform API unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}}}}},"/fiscal-connection":{"get":{"tags":["Accounting"],"operationId":"getFiscalAuthorityConnection","summary":"Safe company connection status; no credentials","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/OrganizationHeader"}],"responses":{"200":{"description":"Provider/environment/status, generation, hasCredentials, validation/audit timestamps and canManage","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object"},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation/request ID echoed for every request."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page (list endpoints only)."}},"additionalProperties":true}}}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden (scope or tenant access)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}}}},"post":{"tags":["Accounting"],"operationId":"manageFiscalAuthorityConnection","summary":"Company admin connect/test/update/disconnect; canonical Platform enforces authority","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/OrganizationHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action","generation"],"properties":{"action":{"type":"string","enum":["connect","test","update","disconnect"]},"generation":{"type":"integer","minimum":0},"username":{"type":"string","maxLength":80,"writeOnly":true},"password":{"type":"string","maxLength":512,"writeOnly":true}}}}}},"responses":{"200":{"description":"Safe status only; never echoes a credential","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object"},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation/request ID echoed for every request."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page (list endpoints only)."}},"additionalProperties":true}}}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden (scope or tenant access)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Generation changed or validation already pending"},"422":{"description":"Taxpayer mismatch or invalid connection input"}}}},"/documents/{documentId}":{"get":{"tags":["Documents"],"operationId":"getDocument","summary":"Get one document by id (tenant-scoped)","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/OrganizationHeader"},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Document detail (values owned by the platform domain)","headers":{"X-Request-Id":{"description":"Correlation/request ID for support and log lookup.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["id","businessProfileId","status","category","reference","supplierName","invoiceNumber","issueDate","currency","netAmount","taxAmount","grossAmount","duplicate","updatedAt"],"properties":{"documentId":{"type":"string","description":"Additive canonical identifier alias used by mobile."},"fiscalRegistry":{"type":["object","null"],"additionalProperties":false,"properties":{"state":{"type":"string","enum":["matched","possible_match","not_found","unavailable","not_applicable","review_required"]},"connector":{"type":["string","null"]},"connectorVersion":{"type":["string","null"]},"country":{"type":["string","null"]},"checkedAt":{"type":["string","null"]},"provenance":{"type":"string"},"environment":{"type":"string","enum":["test","production"]},"consultationRole":{"type":"string","enum":["issuer","purchaser"]},"authorityStatus":{"type":"object","properties":{"http":{"type":["number","null"]},"operation":{"type":["number","null"]}}},"matchedFields":{"type":"array","items":{"type":"string"}},"mismatchedFields":{"type":"array","items":{"type":"string"}},"candidateCount":{"type":["number","null"]},"authorityReference":{"type":["string","null"]},"retryable":{"type":"boolean"},"errorCategory":{"type":["string","null"]}}},"id":{"type":"string"},"businessProfileId":{"type":"string"},"status":{"type":["string","null"]},"category":{"type":["string","null"]},"reference":{"type":["string","null"]},"supplierName":{"type":["string","null"]},"supplierDisplayName":{"type":["string","null"]},"supplierLegalName":{"type":["string","null"]},"supplierTradeName":{"type":["string","null"]},"supplierEstablishmentName":{"type":["string","null"]},"supplierTaxId":{"type":["string","null"]},"invoiceNumber":{"type":["string","null"]},"issueDate":{"type":["string","null"],"format":"date"},"currency":{"type":["string","null"],"example":"EUR"},"netAmount":{"type":["number","null"]},"taxAmount":{"type":["number","null"]},"grossAmount":{"type":["number","null"]},"duplicate":{"type":"string","enum":["none","possible","confirmed"],"description":"Duplicate verdict exactly as computed by the owning platform domain."},"documentVersionId":{"type":["string","null"]},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation/request ID echoed for every request."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page (list endpoints only)."}},"additionalProperties":true}}}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden (scope or tenant access)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"502":{"description":"FiscalVault Platform API response contract violation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"503":{"description":"FiscalVault Platform API unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}}}}},"/accounting-packages":{"get":{"tags":["Accounting"],"operationId":"getMobilePackages","summary":"Read canonical monthly accounting packages through the tenant-authorized Platform API","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/OrganizationHeader"}],"responses":{"200":{"description":"Canonical monthly delivery projection including safe fiscal evidence","headers":{"X-Request-Id":{"description":"Correlation/request ID for support and log lookup.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"periods":{"type":"array","items":{"type":"object","description":"Canonical Platform monthly delivery; no Nexus persistence or recalculation.","properties":{"packageKey":{"type":"string"},"packageId":{"type":"string"},"businessProfileId":{"type":"string"},"businessName":{"type":"string"},"period":{"type":"string"},"label":{"type":"string"},"status":{"type":"string"},"counts":{"type":"object","additionalProperties":{"type":"number"}},"progress":{"type":"number"},"total":{"type":["object","null"],"properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"documents":{"type":"array","items":{"type":"object","properties":{"document_id":{"type":"string"},"business_profile_id":{"type":"string"},"fiscalRegistry":{"type":["object","null"],"additionalProperties":false,"properties":{"state":{"type":"string","enum":["matched","possible_match","not_found","unavailable","not_applicable","review_required"]},"connector":{"type":["string","null"]},"connectorVersion":{"type":["string","null"]},"country":{"type":["string","null"]},"checkedAt":{"type":["string","null"]},"provenance":{"type":"string"},"environment":{"type":"string","enum":["test","production"]},"consultationRole":{"type":"string","enum":["issuer","purchaser"]},"authorityStatus":{"type":"object","properties":{"http":{"type":["number","null"]},"operation":{"type":["number","null"]}}},"matchedFields":{"type":"array","items":{"type":"string"}},"mismatchedFields":{"type":"array","items":{"type":"string"}},"candidateCount":{"type":["number","null"]},"authorityReference":{"type":["string","null"]},"retryable":{"type":"boolean"},"errorCategory":{"type":["string","null"]}}},"document_status":{"type":["string","null"]},"lifecycle_status":{"type":"string"},"lifecycleStatus":{"type":"string"},"lifecycleLabel":{"type":"string"},"supplier_name":{"type":["string","null"]},"invoice_number":{"type":["string","null"]},"issue_date":{"type":["string","null"]},"updated_at":{"type":"string"},"total_amount":{"type":["number","null"]},"currency":{"type":["string","null"]},"reference":{"type":["string","null"]},"journey":{"type":"object"},"workflow":{"type":"object","properties":{"state":{"type":"string"}}},"packagedAt":{"type":"string"}}}}}}},"current":{"anyOf":[{"type":"object","description":"Canonical Platform monthly delivery; no Nexus persistence or recalculation.","properties":{"packageKey":{"type":"string"},"packageId":{"type":"string"},"businessProfileId":{"type":"string"},"businessName":{"type":"string"},"period":{"type":"string"},"label":{"type":"string"},"status":{"type":"string"},"counts":{"type":"object","additionalProperties":{"type":"number"}},"progress":{"type":"number"},"total":{"type":["object","null"],"properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"documents":{"type":"array","items":{"type":"object","properties":{"document_id":{"type":"string"},"business_profile_id":{"type":"string"},"fiscalRegistry":{"type":["object","null"],"additionalProperties":false,"properties":{"state":{"type":"string","enum":["matched","possible_match","not_found","unavailable","not_applicable","review_required"]},"connector":{"type":["string","null"]},"connectorVersion":{"type":["string","null"]},"country":{"type":["string","null"]},"checkedAt":{"type":["string","null"]},"provenance":{"type":"string"},"environment":{"type":"string","enum":["test","production"]},"consultationRole":{"type":"string","enum":["issuer","purchaser"]},"authorityStatus":{"type":"object","properties":{"http":{"type":["number","null"]},"operation":{"type":["number","null"]}}},"matchedFields":{"type":"array","items":{"type":"string"}},"mismatchedFields":{"type":"array","items":{"type":"string"}},"candidateCount":{"type":["number","null"]},"authorityReference":{"type":["string","null"]},"retryable":{"type":"boolean"},"errorCategory":{"type":["string","null"]}}},"document_status":{"type":["string","null"]},"lifecycle_status":{"type":"string"},"lifecycleStatus":{"type":"string"},"lifecycleLabel":{"type":"string"},"supplier_name":{"type":["string","null"]},"invoice_number":{"type":["string","null"]},"issue_date":{"type":["string","null"]},"updated_at":{"type":"string"},"total_amount":{"type":["number","null"]},"currency":{"type":["string","null"]},"reference":{"type":["string","null"]},"journey":{"type":"object"},"workflow":{"type":"object","properties":{"state":{"type":"string"}}},"packagedAt":{"type":"string"}}}}}},{"type":"null"}]}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation/request ID echoed for every request."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page (list endpoints only)."}},"additionalProperties":true}}}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden (scope or tenant access)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"502":{"description":"FiscalVault Platform API response contract violation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"503":{"description":"FiscalVault Platform API unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}}}}},"/accounting-packages/{packageKey}":{"get":{"tags":["Accounting"],"operationId":"getMobilePackage","summary":"Read canonical monthly accounting packages through the tenant-authorized Platform API","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/OrganizationHeader"},{"name":"packageKey","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Canonical monthly delivery projection including safe fiscal evidence","headers":{"X-Request-Id":{"description":"Correlation/request ID for support and log lookup.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","description":"Canonical Platform monthly delivery; no Nexus persistence or recalculation.","properties":{"packageKey":{"type":"string"},"packageId":{"type":"string"},"businessProfileId":{"type":"string"},"businessName":{"type":"string"},"period":{"type":"string"},"label":{"type":"string"},"status":{"type":"string"},"counts":{"type":"object","additionalProperties":{"type":"number"}},"progress":{"type":"number"},"total":{"type":["object","null"],"properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"documents":{"type":"array","items":{"type":"object","properties":{"document_id":{"type":"string"},"business_profile_id":{"type":"string"},"fiscalRegistry":{"type":["object","null"],"additionalProperties":false,"properties":{"state":{"type":"string","enum":["matched","possible_match","not_found","unavailable","not_applicable","review_required"]},"connector":{"type":["string","null"]},"connectorVersion":{"type":["string","null"]},"country":{"type":["string","null"]},"checkedAt":{"type":["string","null"]},"provenance":{"type":"string"},"environment":{"type":"string","enum":["test","production"]},"consultationRole":{"type":"string","enum":["issuer","purchaser"]},"authorityStatus":{"type":"object","properties":{"http":{"type":["number","null"]},"operation":{"type":["number","null"]}}},"matchedFields":{"type":"array","items":{"type":"string"}},"mismatchedFields":{"type":"array","items":{"type":"string"}},"candidateCount":{"type":["number","null"]},"authorityReference":{"type":["string","null"]},"retryable":{"type":"boolean"},"errorCategory":{"type":["string","null"]}}},"document_status":{"type":["string","null"]},"lifecycle_status":{"type":"string"},"lifecycleStatus":{"type":"string"},"lifecycleLabel":{"type":"string"},"supplier_name":{"type":["string","null"]},"invoice_number":{"type":["string","null"]},"issue_date":{"type":["string","null"]},"updated_at":{"type":"string"},"total_amount":{"type":["number","null"]},"currency":{"type":["string","null"]},"reference":{"type":["string","null"]},"journey":{"type":"object"},"workflow":{"type":"object","properties":{"state":{"type":"string"}}},"packagedAt":{"type":"string"}}}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation/request ID echoed for every request."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page (list endpoints only)."}},"additionalProperties":true}}}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden (scope or tenant access)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"502":{"description":"FiscalVault Platform API response contract violation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"503":{"description":"FiscalVault Platform API unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}}}}},"/accounting-periods/{period}":{"get":{"tags":["Accounting"],"operationId":"getAccountingPeriodSummary","summary":"Accounting-period summary using existing FiscalVault semantics","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/OrganizationHeader"},{"$ref":"#/components/parameters/PeriodPath"}],"responses":{"200":{"description":"Accounting-period summary aggregated (arithmetically only) across the tenant's business profiles","headers":{"X-Request-Id":{"description":"Correlation/request ID for support and log lookup.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["organizationId","period","receivedCount","accountingEligibleCount","excludedDuplicateCount","counts","totalsByCurrency","documents"],"properties":{"organizationId":{"type":"string"},"period":{"type":"string","example":"2026-08"},"receivedCount":{"type":"integer"},"accountingEligibleCount":{"type":"integer"},"excludedDuplicateCount":{"type":"integer"},"counts":{"type":"object","additionalProperties":{"type":"integer"},"description":"Document counts keyed by the stage values assigned by the owning domain."},"totalsByCurrency":{"type":"object","additionalProperties":{"type":"object","required":["net","tax","gross"],"properties":{"net":{"type":"number"},"tax":{"type":"number"},"gross":{"type":"number"}}},"description":"Net/tax/gross totals per ISO currency code."},"documents":{"type":"array","items":{"type":"object","required":["documentId","businessProfileId","stage","accountingEligible","duplicateState","supplierName","issueDate"],"properties":{"documentId":{"type":["string","null"]},"businessProfileId":{"type":"string"},"stage":{"type":"string","description":"Period stage assigned by the owning domain."},"accountingEligible":{"type":"boolean"},"duplicateState":{"type":"string","description":"Duplicate gate state assigned upstream."},"supplierName":{"type":["string","null"]},"issueDate":{"type":["string","null"],"format":"date"}}}}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation/request ID echoed for every request."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page (list endpoints only)."}},"additionalProperties":true}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden (scope or tenant access)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"502":{"description":"FiscalVault Platform API response contract violation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"503":{"description":"FiscalVault Platform API unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}}}}},"/accountant-overview":{"get":{"tags":["Accounting"],"operationId":"getAccountantOverview","summary":"Accountant Overview foundation: Portfolio Pulse, Closing Progress, Attention Companies, Portfolio Health, Work Queue Preview","description":"Portfolio-scope read of the authoritative FiscalVault Platform API accountant-overview projection. The scope is the caller's authorized portfolio (all memberships), enforced upstream via the forwarded token, unless narrowed with ?organizationId — which must be one of the principal's memberships (403 otherwise). This route is NOT tenant-scoped: it does not require X-Organization-Id. Every metric (accounting eligibility, duplicate verdicts, closing progress, readiness, health) is computed by the owning platform domain; Nexus passes it through verbatim and never recalculates.","security":[{"bearerAuth":[]}],"parameters":[{"name":"period","in":"query","required":false,"description":"Accounting period in \"YYYY-MM\" format. Defaults to the current period (upstream convention).","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"name":"organizationId","in":"query","required":false,"description":"Narrows the overview to one organization. Must be one of the principal's memberships; non-memberships are rejected (403).","schema":{"type":"string"}},{"name":"workQueueLimit","in":"query","required":false,"description":"Bounded work-queue preview size (upstream default 20).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Accountant overview (all metrics owned by the platform domain)","headers":{"X-Request-Id":{"description":"Correlation/request ID for support and log lookup.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["period","portfolioPulse","closingProgress","attentionCompanies","portfolioHealth","workQueuePreview","documentIntelligence","packagesAndExports","vatAccountingSnapshot","activityStream"],"description":"Every metric is owned by the platform domain and passed through verbatim; Nexus never recalculates eligibility, duplicates, progress, readiness, health, document intelligence, VAT/accounting totals, package/export semantics, or activity events.","properties":{"period":{"type":"string","example":"2026-08"},"portfolioPulse":{"type":"object","required":["companiesInScope","documentsReceived","accountingEligible","ready","requiresAttention","duplicatesExcluded","readinessPercentage"],"properties":{"companiesInScope":{"type":"integer"},"documentsReceived":{"type":"integer"},"accountingEligible":{"type":"integer"},"ready":{"type":"integer"},"requiresAttention":{"type":"integer"},"duplicatesExcluded":{"type":"integer"},"readinessPercentage":{"type":["number","null"]}}},"closingProgress":{"type":"object","required":["percentage","companyCount","states"],"properties":{"percentage":{"type":["number","null"],"description":"Authoritative closing progress percentage; null when unavailable."},"companyCount":{"type":"integer"},"states":{"type":"array","items":{"type":"object","required":["code","label","count","percentage"],"properties":{"code":{"type":"string","description":"Canonical closing-state code (needs_review | confirmed | payment | ready | accounted)."},"label":{"type":"string"},"count":{"type":"integer"},"percentage":{"type":["number","null"],"description":"Share of the accounting-eligible denominator; null when it is empty."}}}}}},"attentionCompanies":{"type":"array","items":{"type":"object","required":["businessProfileId","organizationId","companyName","period","health","documentCount","accountingEligibleCount","duplicatesExcluded","readinessPercentage","reasons","summary"],"properties":{"businessProfileId":{"type":"string"},"organizationId":{"type":"string"},"companyName":{"type":"string"},"period":{"type":"string","example":"2026-08"},"health":{"type":"string","enum":["on_track","at_risk","blocked"],"description":"Health verdict owned by the platform domain."},"documentCount":{"type":"integer"},"accountingEligibleCount":{"type":"integer"},"duplicatesExcluded":{"type":"integer"},"readinessPercentage":{"type":["number","null"],"description":"Authoritative accounting progress percentage; null when unavailable."},"reasons":{"type":"array","items":{"type":"object","required":["code","label","count"],"properties":{"code":{"type":"string"},"label":{"type":"string"},"count":{"type":"integer"}}}},"summary":{"type":"string","description":"Deterministic sentence built upstream from the reasons; never generated by Nexus."}}},"description":"Enriched attention rows (reasons + summary), in upstream rank order."},"portfolioHealth":{"type":"array","items":{"type":"object","required":["businessProfileId","organizationId","companyName","period","health","readinessPercentage","documentCount","accountingEligibleCount","duplicatesExcluded","attentionCount","closingStateCode","closingStateLabel"],"properties":{"businessProfileId":{"type":"string"},"organizationId":{"type":"string"},"companyName":{"type":"string"},"period":{"type":"string","example":"2026-08"},"health":{"type":"string","enum":["on_track","at_risk","blocked"],"description":"Health verdict owned by the platform domain."},"readinessPercentage":{"type":["number","null"],"description":"Authoritative accounting progress percentage; null when unavailable."},"documentCount":{"type":"integer"},"accountingEligibleCount":{"type":"integer"},"duplicatesExcluded":{"type":"integer"},"attentionCount":{"type":"integer"},"closingStateCode":{"type":["string","null"],"description":"Dominant closing state for the period; null when no documents are in scope."},"closingStateLabel":{"type":["string","null"]}}},"description":"Enriched per-company health rows for the full authorized scope."},"workQueuePreview":{"type":"array","items":{"type":"object","required":["kind","businessProfileId","organizationId","companyName","documentId","supplierName","issueDate","title","rank","taskType","taskLabel","reasonCode","reasonLabel","priority","createdAt","documentNumber","documentType","documentDate"],"properties":{"kind":{"type":"string","enum":["duplicate_resolution","document_review","accounting_finding"]},"businessProfileId":{"type":"string"},"organizationId":{"type":"string"},"companyName":{"type":"string"},"documentId":{"type":["string","null"]},"supplierName":{"type":["string","null"]},"issueDate":{"type":["string","null"],"format":"date"},"title":{"type":["string","null"]},"rank":{"type":"integer","description":"Upstream ranking (ascending)."},"taskType":{"type":"string","enum":["duplicate_resolution","document_review","accounting_finding"]},"taskLabel":{"type":"string"},"reasonCode":{"type":"string"},"reasonLabel":{"type":"string"},"priority":{"type":["string","null"],"description":"No authoritative task priority exists upstream yet; null until one does."},"createdAt":{"type":["string","null"],"format":"date-time"},"documentNumber":{"type":["string","null"]},"documentType":{"type":["string","null"]},"documentDate":{"type":["string","null"],"format":"date"}}},"description":"Ranked next actions (bounded by workQueueLimit)."},"documentIntelligence":{"type":"object","required":["processed","automaticallyResolved","automationRatePercentage","requiresReview","highRiskFindings","duplicateGroups","duplicatesExcluded"],"properties":{"processed":{"type":"integer"},"automaticallyResolved":{"type":["number","null"],"description":"Nullable because zero-touch authority is not yet persisted."},"automationRatePercentage":{"type":["number","null"],"description":"Nullable until automaticallyResolved becomes authoritative."},"requiresReview":{"type":"integer"},"highRiskFindings":{"type":"integer"},"duplicateGroups":{"type":["number","null"],"description":"Nullable because duplicate group/cluster identity is not currently persisted."},"duplicatesExcluded":{"type":"integer","description":"Supplied by the platform; consistent with portfolioPulse.duplicatesExcluded by contract."}},"description":"Enriched Document Intelligence projection. Nullable fields are preserved as null; Nexus never derives or recomputes them."},"packagesAndExports":{"type":"object","required":["packageSummary","recentExports"],"properties":{"packageSummary":{"type":"object","required":["companyCount","ready","inReview","blocked","notStarted","other"],"properties":{"companyCount":{"type":"integer","description":"Portfolio companies in scope."},"ready":{"type":["number","null"],"description":"approved canonical package snapshots."},"inReview":{"type":["number","null"],"description":"validated canonical package snapshots."},"blocked":{"type":["number","null"],"description":"invalidated canonical package snapshots."},"notStarted":{"type":["number","null"],"description":"Companies in scope with no live snapshot for the selected period."},"other":{"type":["number","null"],"description":"Live packages in statuses outside the four product buckets."}}},"recentExports":{"type":["array","null"],"items":{"type":"object","required":["companyId","companyName","providerCode","providerLabel","exportedAt","status"],"properties":{"companyId":{"type":"string"},"companyName":{"type":"string"},"providerCode":{"type":"string","description":"Connector/provider identity (connector_id)."},"providerLabel":{"type":["string","null"],"description":"Customer-safe destination label from the existing label authority."},"exportedAt":{"type":["string","null"],"format":"date-time"},"status":{"type":"string"}}},"description":"Real export executions only, most recent first, bounded upstream. null when no authoritative export execution exists."}},"description":"Enriched Packages & Exports projection. Buckets, nulls and export events are preserved verbatim; Nexus derives no package lifecycle and infers no export from configuration."},"vatAccountingSnapshot":{"type":"object","required":["currency","taxableBase","taxAmount","grossAmount","eligibleDocumentCount","excludedDocumentCount","excludedGrossAmount","vatBreakdown","currencies","multiCurrency"],"properties":{"currency":{"type":["string","null"],"description":"The single portfolio currency (ISO code); null when the portfolio is multi-currency or has no eligible documents."},"taxableBase":{"type":["string","null"],"description":"Canonical decimal-string taxable base over accounting-eligible documents; null on multi-currency portfolios or when not authoritatively available."},"taxAmount":{"type":["string","null"],"description":"Canonical decimal-string tax total; null like taxableBase."},"grossAmount":{"type":["string","null"],"description":"Canonical decimal-string gross total; null like taxableBase."},"eligibleDocumentCount":{"type":"integer","description":"Accounting-eligible documents in scope (platform authority)."},"excludedDocumentCount":{"type":"integer","description":"Documents excluded upstream (incl. confirmed duplicates); never mixed into eligible totals."},"excludedGrossAmount":{"type":["string","null"],"description":"Canonical decimal-string gross total of excluded documents; null on currency ambiguity or lack of authority — never converted to zero."},"vatBreakdown":{"type":["array","null"],"items":{"type":"object","required":["rate","taxableBase","taxAmount"],"properties":{"rate":{"type":["string","null"],"description":"VAT rate as a canonical decimal string; null when unknown upstream."},"taxableBase":{"type":"string","description":"Canonical decimal-string base at this rate."},"taxAmount":{"type":"string","description":"Canonical decimal-string tax at this rate."}}},"description":"Structured per-rate VAT breakdown from the platform's VAT authority; null when no VAT groups exist upstream. Never aggregated or reconciled by Nexus."},"currencies":{"type":"array","items":{"type":"string"},"description":"Currencies observed among eligible documents (authoritative, sorted)."},"multiCurrency":{"type":"boolean","description":"True when more than one currency is in scope; monetary totals stay null and NO FX conversion is performed."}},"description":"VAT / Accounting Snapshot projection. Decimal-string money, multi-currency gap (null money + currencies[]) and the per-rate breakdown pass through verbatim; Nexus performs no FX conversion, no summing and no VAT recomputation."},"activityStream":{"type":"object","required":["scope","items","hasMore"],"properties":{"scope":{"type":"string","enum":["recent_portfolio"],"description":"Explicit scope: recent PORTFOLIO activity, not accounting-period activity."},"items":{"type":"array","description":"Recent portfolio events in upstream order (occurredAt DESC, stable eventId tiebreak); bounded upstream (default 20). Order is preserved verbatim — Nexus never sorts, re-ranks or deduplicates.","items":{"type":"object","required":["eventId","eventType","occurredAt","companyId","companyName","documentId","packageId","title","description","severity","metadata"],"properties":{"eventId":{"type":"string","description":"Stable identity of the persisted source event (source row + lifecycle step)."},"eventType":{"type":"string","enum":["DOCUMENT_RECEIVED","DUPLICATE_DETECTED","DUPLICATE_CONFIRMED","DUPLICATE_DISMISSED","ACCOUNTING_FINDING_CREATED","ACCOUNTING_FINDING_RESOLVED","PACKAGE_GENERATED","PACKAGE_VALIDATED","PACKAGE_APPROVED","PACKAGE_BLOCKED","EXPORT_REQUESTED","EXPORT_COMPLETED","EXPORT_FAILED"],"description":"Closed platform-owned taxonomy. Nexus accepts only these types and never invents, renames or merges events; banking events are not authoritative upstream and never appear."},"occurredAt":{"type":"string","format":"date-time","description":"Authoritative domain timestamp (ISO 8601)."},"companyId":{"type":["string","null"],"description":"Business profile the event belongs to; null when not attributable upstream."},"companyName":{"type":["string","null"],"description":"Display name of the company; null when not authoritative upstream."},"documentId":{"type":["string","null"],"description":"Related document, when the event has document context; otherwise null."},"packageId":{"type":["string","null"],"description":"Related canonical package, when the event has package context; otherwise null."},"title":{"type":"string","description":"Platform-owned deterministic title; never AI generated."},"description":{"type":["string","null"],"description":"Optional human detail (e.g. supplier name); null when absent upstream."},"severity":{"type":["string","null"],"enum":["critical","warning","info",null],"description":"Platform-assigned severity; null when the event carries none."},"metadata":{"type":["object","null"],"additionalProperties":{"type":["string","number"]},"description":"Optional structured context (e.g. supplierName, documentNumber, packageRevision); null when absent upstream. Passed through verbatim."}}}},"hasMore":{"type":"boolean","description":"True when more events exist beyond the upstream bound; Nexus adds no pagination."}},"description":"Activity Stream projection: RECENT PORTFOLIO activity (never accounting-period activity — events are not filtered by ?period). Closed event taxonomy, upstream ordering, bounded items and hasMore pass through verbatim; Nexus generates, infers or re-orders no events."}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation/request ID echoed for every request."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page (list endpoints only)."}},"additionalProperties":true}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden (scope or tenant access)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"502":{"description":"FiscalVault Platform API response contract violation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"503":{"description":"FiscalVault Platform API unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}}}}},"/accountant-packages/{period}":{"get":{"tags":["Accounting"],"operationId":"getAccountantPackage","summary":"Period-level accountant package (capability not exposed upstream)","description":"The FiscalVault Platform API does not expose a period-level package capability. Nexus reports this truthfully as 501 UPSTREAM_CAPABILITY_MISSING — it is never emulated. Use the per-document endpoint /documents/{documentId}/package instead.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/OrganizationHeader"},{"$ref":"#/components/parameters/PeriodPath"}],"responses":{"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden (scope or tenant access)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"501":{"description":"Capability not exposed by the FiscalVault Platform API yet (reported truthfully, never emulated)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"502":{"description":"FiscalVault Platform API response contract violation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"503":{"description":"FiscalVault Platform API unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}}}}},"/documents/{documentId}/package":{"get":{"tags":["Accounting"],"operationId":"getDocumentPackage","summary":"Canonical accountant package snapshot for one document","description":"Read-only projection (snapshot revision, readiness, fingerprint, serializer identity, trust score) owned by the existing platform domain; Nexus passes it through verbatim.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/OrganizationHeader"},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"includePayload","in":"query","required":false,"description":"When true, embeds the canonical ERP-independent package payload.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Document package snapshot","headers":{"X-Request-Id":{"description":"Correlation/request ID for support and log lookup.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["documentId","revision","status","readiness","readinessDimension","packageFingerprint","schemaVersion","serializer","trustScore","createdAt"],"properties":{"documentId":{"type":"string"},"revision":{"type":"integer","description":"Canonical snapshot revision."},"status":{"type":"string","description":"Snapshot status owned by the platform."},"readiness":{"type":"string","description":"Package readiness (human-workflow dimension)."},"readinessDimension":{"type":"string"},"packageFingerprint":{"type":["string","null"]},"schemaVersion":{"type":"string"},"serializer":{"type":"string","description":"\"serializerId@serializerVersion\"."},"trustScore":{"type":["number","null"]},"createdAt":{"type":"string","format":"date-time"},"payload":{"description":"Canonical ERP-independent package payload. Present only with ?includePayload=true."}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation/request ID echoed for every request."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page (list endpoints only)."}},"additionalProperties":true}}}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden (scope or tenant access)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"502":{"description":"FiscalVault Platform API response contract violation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"503":{"description":"FiscalVault Platform API unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}}}}},"/upload-sessions":{"post":{"tags":["Uploads"],"operationId":"createUploadSession","summary":"Authorize a direct-to-storage upload. Nexus never proxies file bytes; the client PUTs to the returned signed destination and the existing ingestion pipeline consumes the object.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/OrganizationHeader"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fileName","contentType","byteSize"],"properties":{"fileName":{"type":"string","minLength":1,"maxLength":255},"contentType":{"type":"string","enum":["application/pdf","image/png","image/jpeg"]},"byteSize":{"type":"integer","minimum":1,"maximum":52428800},"documentKind":{"type":"string","maxLength":64}}}}}},"responses":{"201":{"description":"Upload session created","headers":{"X-Request-Id":{"description":"Correlation/request ID for support and log lookup.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["uploadSessionId","storageKey","provider","method","url","headers","expiresAt"],"properties":{"uploadSessionId":{"type":"string","format":"uuid"},"storageKey":{"type":"string"},"provider":{"type":"string","enum":["STUB","UNAVAILABLE"],"description":"Upload provider backing the session. \"STUB\" appears only in explicit local/test mode; \"UNAVAILABLE\" means the FiscalVault Platform API does not expose upload signing yet and the request fails truthfully with 501."},"method":{"type":"string","enum":["PUT"]},"url":{"type":"string","description":"Short-lived signed destination in the existing FiscalVault object storage. PUT the file bytes here directly."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Headers the client MUST send on the PUT (e.g. content-type)."},"expiresAt":{"type":"string","format":"date-time","description":"Nexus-stamped upload intent expiry (default TTL 900s). Uploads after this time are rejected by the ingestion boundary."}}},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation/request ID echoed for every request."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page (list endpoints only)."}},"additionalProperties":true}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden (scope or tenant access)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"502":{"description":"FiscalVault Platform API response contract violation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"503":{"description":"FiscalVault Platform API unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}}}}},"/accounting-office":{"post":{"tags":["Accounting Office"],"operationId":"createAccountingOffice","summary":"Self-service Accounting Office creation (atomic office + OWNER membership)","description":"Creates the caller's Accounting Office and their OWNER membership in one atomic command (no frontend orchestration of office-then-membership). Requires an ACTIVE Accountant Workspace product entitlement — authentication alone is not product access (403 PRODUCT_ACCESS_DENIED otherwise). The new office starts DRAFT (publication) / UNVERIFIED (verification) and is NOT marketplace-visible. Milestone 1: one office per user — a second creation fails 409 OFFICE_ALREADY_EXISTS. Safe to retry with the same Idempotency-Key.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","countryCode"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Legal/public working name (full office Profile is a later wave)."},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$","example":"PT","description":"ISO 3166-1 alpha-2; normalized to uppercase."},"taxIdentifier":{"type":["string","null"],"maxLength":64,"description":"Optional VAT/NIF identifier (stored, not validated, in Wave 1)."}}}}}},"responses":{"201":{"description":"Office created — ACTIVE context with OWNER role","headers":{"X-Request-Id":{"description":"Correlation/request ID for support and log lookup.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/AccountingOfficeContext"},"meta":{"type":"object","required":["requestId"],"properties":{"requestId":{"type":"string","description":"Correlation/request ID echoed for every request."},"nextCursor":{"type":["string","null"],"description":"Opaque cursor for the next page (list endpoints only)."}},"additionalProperties":true}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Forbidden (scope or tenant access)","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"409":{"description":"An accounting office already exists for this account","headers":{"X-Request-Id":{"description":"Correlation/request ID for support and log lookup.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"502":{"description":"FiscalVault Platform API response contract violation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}},"503":{"description":"FiscalVault Platform API unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","ORGANIZATION_ACCESS_DENIED","NO_ORGANIZATION_MEMBERSHIP","NOT_FOUND","DOCUMENT_NOT_FOUND","ORGANIZATION_NOT_FOUND","ACCOUNTING_PERIOD_NOT_FOUND","ACCOUNTANT_PACKAGE_NOT_FOUND","INVALID_PERIOD_FORMAT","INVALID_CURSOR","INVALID_LIMIT","INVALID_SORT","VALIDATION_FAILED","IDEMPOTENCY_KEY_INVALID","METHOD_NOT_ALLOWED","UPSTREAM_UNAVAILABLE","UPSTREAM_CONTRACT_VIOLATION","UPSTREAM_CAPABILITY_MISSING","INTERNAL_ERROR"]},"message":{"type":"string"},"requestId":{"type":"string"},"details":{}}}}}}}}}}}}},"meta":{"requestId":"f7aa6d44-1d25-4354-8708-22876b0c3dd9"}}