{ "openapi": "3.0.0", "paths": { "/health": { "get": { "description": "Returns `{ status: \"ok\" }` when the process is up. No authentication or tenant header required — used by the container/orchestrator health check.", "operationId": "HealthController_health", "parameters": [], "responses": { "200": { "description": "Liveness probe." } }, "summary": "Liveness probe", "tags": [ "system" ] } }, "/info": { "get": { "description": "Returns the derived Keycloak OIDC issuer and realm, plus the ambient tenant (if an `x-tenant-id` is bound). Use it to discover the token endpoint for authenticating other calls.", "operationId": "HealthController_info", "parameters": [], "responses": { "200": { "description": "Derived Keycloak issuer and the ambient tenant, if any." } }, "summary": "Service + Keycloak issuer info", "tags": [ "system" ] } }, "/ingest": { "post": { "description": "Validates the envelope + UAE structure, then the full three-layer PINT-AE rule pack (UBL 2.1 XSD + both Schematron layers), classifies the route, and records the first TRANSPORT leg. Idempotent on (tenant, invoice.id): 201 first time, 200 on identical replay, 409 on same id with different content, 422 on violations.", "operationId": "IngestController_ingest", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestDto" }, "examples": { "valid": { "summary": "Valid invoice", "value": { "sbdh": { "sender": "0235:1000000777", "receiver": "0235:1345678901" }, "invoice": { "id": "INV-2026-000123", "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "issueDate": "2026-07-01", "documentKind": "tax-invoice", "billingMode": "standard", "typeCode": "380", "currencyCode": "AED", "transactionTypeCode": "00000000", "paymentDueDate": "2026-07-31", "businessProcessType": "urn:peppol:bis:billing", "specificationIdentifier": "urn:peppol:pint:billing-1@ae-1", "paymentMeansTypeCode": "30", "payeeFinancialAccountId": "AE070331234567890123456", "seller": { "name": "Falcon Trading LLC", "endpoint": { "scheme": "0235", "value": "1000000777" }, "legalRegistrationId": "CN-1234567", "legalRegistrationIdType": "TL", "taxRegistrationId": "100000077700003", "taxSchemeCode": "VAT", "authorityName": "Department of Economy and Tourism, Dubai", "address": { "addressLine1": "Sheikh Zayed Road 100", "city": "Dubai", "countrySubdivision": "DXB", "countryCode": "AE" } }, "buyer": { "name": "Oasis Retail FZE", "endpoint": { "scheme": "0235", "value": "1345678901" }, "legalRegistrationId": "CN-7654321", "legalRegistrationIdType": "TL", "taxRegistrationId": "134567890123003", "taxSchemeCode": "VAT", "authorityName": "Abu Dhabi Department of Economic Development", "address": { "addressLine1": "Corniche Road 5", "city": "Abu Dhabi", "countrySubdivision": "AUH", "countryCode": "AE" } }, "totals": { "lineNetTotal": "1000.00", "taxExclusiveAmount": "1000.00", "taxTotalAmount": "50.00", "taxInclusiveAmount": "1050.00", "amountDueForPayment": "1050.00" }, "taxBreakdown": [ { "taxableAmount": "1000.00", "taxAmount": "50.00", "categoryCode": "S", "rate": "5" } ], "lines": [ { "id": "1", "quantity": "10", "unitOfMeasureCode": "H87", "netAmount": "1000.00", "itemNetPrice": "100.00", "itemGrossPrice": "100.00", "itemPriceBaseQuantity": "1", "itemTaxCategoryCode": "S", "itemTaxRate": "5", "vatLineAmountAed": "50.00", "lineAmountAed": "1050.00", "itemName": "Widget", "itemDescription": "Standard steel widget" } ] } } }, "invalid": { "summary": "Blank invoice.id → 422", "value": { "sbdh": { "sender": "0235:1000000777", "receiver": "0235:1345678901" }, "invoice": { "id": "", "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "issueDate": "2026-07-01", "documentKind": "tax-invoice", "billingMode": "standard", "typeCode": "380", "currencyCode": "AED", "transactionTypeCode": "00000000", "paymentDueDate": "2026-07-31", "businessProcessType": "urn:peppol:bis:billing", "specificationIdentifier": "urn:peppol:pint:billing-1@ae-1", "paymentMeansTypeCode": "30", "payeeFinancialAccountId": "AE070331234567890123456", "seller": { "name": "Falcon Trading LLC", "endpoint": { "scheme": "0235", "value": "1000000777" }, "legalRegistrationId": "CN-1234567", "legalRegistrationIdType": "TL", "taxRegistrationId": "100000077700003", "taxSchemeCode": "VAT", "authorityName": "Department of Economy and Tourism, Dubai", "address": { "addressLine1": "Sheikh Zayed Road 100", "city": "Dubai", "countrySubdivision": "DXB", "countryCode": "AE" } }, "buyer": { "name": "Oasis Retail FZE", "endpoint": { "scheme": "0235", "value": "1345678901" }, "legalRegistrationId": "CN-7654321", "legalRegistrationIdType": "TL", "taxRegistrationId": "134567890123003", "taxSchemeCode": "VAT", "authorityName": "Abu Dhabi Department of Economic Development", "address": { "addressLine1": "Corniche Road 5", "city": "Abu Dhabi", "countrySubdivision": "AUH", "countryCode": "AE" } }, "totals": { "lineNetTotal": "1000.00", "taxExclusiveAmount": "1000.00", "taxTotalAmount": "50.00", "taxInclusiveAmount": "1050.00", "amountDueForPayment": "1050.00" }, "taxBreakdown": [ { "taxableAmount": "1000.00", "taxAmount": "50.00", "categoryCode": "S", "rate": "5" } ], "lines": [ { "id": "1", "quantity": "10", "unitOfMeasureCode": "H87", "netAmount": "1000.00", "itemNetPrice": "100.00", "itemGrossPrice": "100.00", "itemPriceBaseQuantity": "1", "itemTaxCategoryCode": "S", "itemTaxRate": "5", "vatLineAmountAed": "50.00", "lineAmountAed": "1050.00", "itemName": "Widget", "itemDescription": "Standard steel widget" } ] } } } } } } }, "responses": { "200": { "description": "Duplicate — existing document + route class returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestResultDto" } } } }, "201": { "description": "Created; first TRANSPORT leg + route class recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestResultDto" } } } }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Principal not entitled to this tenant, machine missing axs:ingest scope, human with a read-only role (auditor) on a write, or submission for a missing/non-active tenant (including replay)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "Same invoice.id with different content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResultDto" } } } }, "422": { "description": "Envelope shape, structural/alignment, or rule-pack violations. The response shape is unchanged, but `rule`/`path` carry two kinds of value: our own rule ids with a dotted canonical path rooted at the invoice, with NO `invoice.` prefix (e.g. `MANDATORY_FIELD` at `seller.name`, `SELLER_NOT_REGISTERED` at `seller.endpoint`; non-invoice envelope parts keep their own root, e.g. `sbdh.sender`), and — since the PINT-AE rule pack runs on this path — Schematron rule ids with the finding's XPath location (e.g. `ibr-132-ae`). Only `fatal`/`error` findings reject; warnings never do.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViolationsDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Ingest a canonical invoice (sync)", "tags": [ "ingest" ] } }, "/documents/{integrationId}": { "get": { "description": "Returns the enriched document view: current per-leg states, persisted route class, canonical invoice header, outbound/reporting dispatch and receipt rows, and whether a signed wire artifact (UBL+SBDH) is stored. Requires the `x-tenant-id` header bound to the owning tenant. 404 when the tenant has no document under this integrationId (unknown id, or a document owned by another tenant — never a 200 shell with empty `legs`).", "operationId": "IngestController_get", "parameters": [ { "name": "integrationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current leg states + route class", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentViewDto" } } } }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Principal not entitled to this tenant, machine missing axs:ingest scope, human with a read-only role (auditor) on a write, or submission for a missing/non-active tenant (including replay)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "No document under this integrationId for the bound tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get document detail (legs, route, header, dispatch/receipts, artifact flag)", "tags": [ "ingest" ] } }, "/ingest/file": { "post": { "description": "For machine (ERP) clients: one request instead of POST /validate/file + POST /ingest. The body is a raw UBL 2.1 XML document (one invoice) or a text/csv file (many invoices, one line item per row grouped by invoice_id; the seller comes from the tenant company profile). The file is malware-scanned BEFORE parsing (an infected file is quarantined → 422 FILE_MALWARE; no scanner verdict → 503). Every invoice in the file is then submitted through the same ingest path as POST /ingest — envelope, structure, issuer registration, UUID uniqueness and the full PINT-AE rule pack — and gets its own result: `created`, `duplicate`, `conflict` or `invalid`, with its violations, advisory warnings and the rule-pack report. Idempotent per invoice on (tenant, invoice ID) + content, exactly like POST /ingest: an identical re-upload returns `duplicate` for every already admitted invoice, so the whole call is safe to retry. Invoices are processed in file order; a 5xx means some may already be admitted — retry the identical file. Limits: the request body size limit (413) and the per-file invoice limit (422 FILE_ITEM_LIMIT). 422 is reserved for file-level errors (content type, malware, parse failure, invoice limit, missing company profile for CSV); a file with rejected invoices is a 200 with `summary.invalid > 0`.", "operationId": "IngestFileController_ingestFile", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Per-invoice ingest results; read `summary` and every `items[].kind`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestFileResultDto" } } } }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Principal not entitled to this tenant, machine missing axs:ingest scope, human with a read-only role (auditor), or submission for a missing/non-active tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "413": { "description": "The request body exceeds the configured body size limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "415": { "description": "Unsupported content type (send application/xml, text/xml or text/csv)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "File-level violations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileViolationsDto" } } } }, "503": { "description": "The malware scanner could not give a verdict (fail-closed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Ingest an invoice file (UBL or CSV) in one call", "tags": [ "ingest" ] } }, "/validate/invoice": { "post": { "description": "Maps a canonical invoice to PINT-AE UBL 2.1 and runs the three-layer phive validation, returning the report, the produced UBL, and the derived SBDH. Stateless preview — no signing, persistence, or transport. 422 on envelope/structural violations; 200 with report.valid=false when structurally valid but PINT-AE-invalid.", "operationId": "InvoiceValidationController_validate", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDto" } } } }, "responses": { "200": { "description": "Validation report + produced UBL + derived SBDH", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceUblResultDto" } } } }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Principal not entitled to this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "Envelope shape or structural violations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViolationsDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Validate a canonical invoice (dry-run)", "tags": [ "validation" ] } }, "/validate/file": { "post": { "description": "Parses a raw UBL 2.1 XML body (one invoice) or a text/csv body (many invoices, one line item per row grouped by invoice_id), then runs per-item structural + PINT-AE (phive) validation and the seller-tenant-binding check. Stateless preview — valid items carry a submit-ready {sbdh, invoice} pair for POST /ingest. Every upload (and each base64 attachment inside a UBL) is malware-scanned BEFORE parsing: an infected file is quarantined and answered 422 FILE_MALWARE; when the scanner cannot give a verdict the answer is 503 (fail-closed, never an unscanned preview). 422 on file-level errors (parse failure, item limit, missing company profile for CSV, malware).", "operationId": "FileValidationController_validate", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Per-item validation results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileValidationResultDto" } } } }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Principal not entitled to this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "File-level violations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileViolationsDto" } } } }, "503": { "description": "The malware scanner could not give a verdict (fail-closed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Validate an invoice file (UBL or CSV, dry-run)", "tags": [ "validation" ] } }, "/ingest/async": { "post": { "description": "Enqueues without validating on the request path; returns 202 + a statusUrl to poll. Idempotent per (tenant, body).", "operationId": "AsyncIngestController_enqueue", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestDto" }, "examples": { "valid": { "value": { "sbdh": { "sender": "0235:1000000777", "receiver": "0235:1345678901" }, "invoice": { "id": "INV-2026-000123", "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "issueDate": "2026-07-01", "documentKind": "tax-invoice", "billingMode": "standard", "typeCode": "380", "currencyCode": "AED", "transactionTypeCode": "00000000", "paymentDueDate": "2026-07-31", "businessProcessType": "urn:peppol:bis:billing", "specificationIdentifier": "urn:peppol:pint:billing-1@ae-1", "paymentMeansTypeCode": "30", "payeeFinancialAccountId": "AE070331234567890123456", "seller": { "name": "Falcon Trading LLC", "endpoint": { "scheme": "0235", "value": "1000000777" }, "legalRegistrationId": "CN-1234567", "legalRegistrationIdType": "TL", "taxRegistrationId": "100000077700003", "taxSchemeCode": "VAT", "authorityName": "Department of Economy and Tourism, Dubai", "address": { "addressLine1": "Sheikh Zayed Road 100", "city": "Dubai", "countrySubdivision": "DXB", "countryCode": "AE" } }, "buyer": { "name": "Oasis Retail FZE", "endpoint": { "scheme": "0235", "value": "1345678901" }, "legalRegistrationId": "CN-7654321", "legalRegistrationIdType": "TL", "taxRegistrationId": "134567890123003", "taxSchemeCode": "VAT", "authorityName": "Abu Dhabi Department of Economic Development", "address": { "addressLine1": "Corniche Road 5", "city": "Abu Dhabi", "countrySubdivision": "AUH", "countryCode": "AE" } }, "totals": { "lineNetTotal": "1000.00", "taxExclusiveAmount": "1000.00", "taxTotalAmount": "50.00", "taxInclusiveAmount": "1050.00", "amountDueForPayment": "1050.00" }, "taxBreakdown": [ { "taxableAmount": "1000.00", "taxAmount": "50.00", "categoryCode": "S", "rate": "5" } ], "lines": [ { "id": "1", "quantity": "10", "unitOfMeasureCode": "H87", "netAmount": "1000.00", "itemNetPrice": "100.00", "itemGrossPrice": "100.00", "itemPriceBaseQuantity": "1", "itemTaxCategoryCode": "S", "itemTaxRate": "5", "vatLineAmountAed": "50.00", "lineAmountAed": "1050.00", "itemName": "Widget", "itemDescription": "Standard steel widget" } ] } } } } } } }, "responses": { "202": { "description": "Accepted; queued for async processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncAcceptedDto" } } } }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Principal not entitled to this tenant, machine missing axs:ingest scope, human with a read-only role (auditor) on a write, or submission for a missing/non-active tenant (including replay)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Ingest a canonical invoice (async)", "tags": [ "ingest" ] } }, "/ingest/{messageId}": { "get": { "description": "Returns the durable status of an async-ingest job (`queued`/`processing`/`done`/`invalid`/`failed`). `done` requires inspecting result.kind: created, duplicate, or conflict. `invalid` is a terminal validation rejection, distinct from `failed` (infrastructure error after retries). Neither 202 nor done proves delivery or compliance. Requires the `x-tenant-id` header.", "operationId": "AsyncIngestController_status", "parameters": [ { "name": "messageId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Async job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Principal not entitled to this tenant, machine missing axs:ingest scope, human with a read-only role (auditor) on a write, or submission for a missing/non-active tenant (including replay)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "Unknown messageId for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get async ingest job status", "tags": [ "ingest" ] } }, "/inbound/webhook": { "post": { "description": "Shared-secret HMAC-guarded webhook (x-axs-signature, interim seam ahead of the G2-gated real Tickstar callback auth). Enqueues one idempotent job (jobId = backendTxId); not a tenant-header route — the tenant is discovered mid-pipeline.", "operationId": "InboundController_webhook", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDto" } } } }, "responses": { "202": { "description": "Accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundAcceptedDto" } } } }, "401": { "description": "Missing or invalid webhook signature" } }, "summary": "Receive a Peppol inbound-document notification (C3)", "tags": [ "inbound" ] } }, "/outbound/receipt/webhook": { "post": { "description": "Shared-secret HMAC-guarded webhook (x-axs-signature, keyed by AXS_OUTBOUND_WEBHOOK_SECRET — an interim seam ahead of the G2-gated real Tickstar callback auth, independent of the inbound webhook secret). Reconciles the TRANSPORT leg to DELIVERED / TRANSMISSION_FAILED, or leaves it pending for a non-terminal AS4 state. A terminal state with unknown outcome returns unresolved without inventing a delivery result.", "operationId": "OutboundController_webhook", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptDto" } } } }, "responses": { "202": { "description": "Accepted and reconciled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutboundReceiptAcceptedDto" } } } }, "401": { "description": "Missing or invalid webhook signature" } }, "summary": "Receive an outbound (C2→C3) AS4 transport-receipt notification", "tags": [ "outbound" ] } }, "/reporting/mls/webhook": { "post": { "description": "Shared-secret HMAC-guarded webhook (x-axs-signature, keyed by AXS_REPORTING_WEBHOOK_SECRET — an interim seam ahead of the G2-gated real Tickstar callback auth, independent of the inbound/outbound webhook secrets). Reconciles the C5_C2/C5_C3 leg to REPORTED on a POSITIVE outcome, or REPORTING_FAILED on a NEGATIVE outcome — including an evidence-backed reopen when the leg had already reached REPORTED (a late negative MLS).", "operationId": "ReportingController_webhook", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingMlsDto" } } } }, "responses": { "202": { "description": "Accepted and reconciled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportingMlsAcceptedDto" } } } }, "401": { "description": "Missing or invalid webhook signature" } }, "summary": "Receive a C5 FTA/TDD MLR/MLS (Message Level Response/Status) notification", "tags": [ "reporting" ] } }, "/documents": { "get": { "description": "Queries the eventual-consistent §8 CQRS search read-model (not the authoritative per-document leg-state store). Supports free text, per-field filters, comma-separated facets, opaque cursor or offset pagination, and an optional explicit `sort` (`issueDate`, `invoiceId`, `buyerName`, `sellerName`, `taxInclusiveAmount`) with `order` (`asc`/`desc`; default `desc` for date/amount, `asc` for text). Without `sort`, a free-text query is ordered by relevance and a list query by `integrationId`. `category` filters (and the `category` facet counts) the six document categories derived from the `documentKind` × `typeCode` pair (`tax-invoice`, `commercial-invoice`, `tax-credit-note`, `commercial-credit-note`, `self-billed-tax-invoice`, `self-billed-tax-credit-note`); a document with any other pair has no category. `docType` keeps filtering the raw `typeCode`. Each item carries `billingMode`, the stored value of the authoritative document (`standard`, `self-billed`, or `unknown` when it cannot be read); it is never derived from `typeCode`, and the `category` filter does not use it. Facets are disjunctive (ADR-0241): each facet is counted with every active filter EXCEPT its own dimension, so an active `category` (or `state`, …) filter narrows the items and `total` but its own facet still lists the other values; the tenant scope always applies. Requires a valid Bearer token and the `x-tenant-id` header bound to the owning tenant. `reportOnly=true` keeps only the documents addressed to a predefined buyer address (reported to the FTA, never sent).", "operationId": "DocumentQueryController_list", "parameters": [ { "name": "q", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "state", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "docType", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "category", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "tax-invoice", "commercial-invoice", "tax-credit-note", "commercial-credit-note", "self-billed-tax-invoice", "self-billed-tax-credit-note" ] } }, { "name": "currency", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "issueDateFrom", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "issueDateTo", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "buyerTrn", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "sellerTrn", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "direction", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "reportingStatus", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "reported", "failed", "pending", "any" ] } }, { "name": "routeClass", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "reportOnly", "required": false, "in": "query", "description": "true = only report-only documents: the buyer electronic address (IBT-049) is one of the predefined addresses 0235:9900000097/098/099, so the document is reported to the FTA only and never sent to the buyer (PINT-AE BIS §1.5.3). Independent of `routeClass`.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "facets", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "schema": { "minimum": 0, "maximum": 9998, "exclusiveMaximum": false, "exclusiveMinimum": false, "type": "integer" } }, { "name": "sort", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "issueDate", "invoiceId", "buyerName", "sellerName", "taxInclusiveAmount" ] } }, { "name": "order", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant-scoped result page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResultPageDto" } } } }, "400": { "description": "Missing/invalid x-tenant-id, a malformed cursor, a malformed query parameter, or an `offset` past the search result window: offset paging reaches at most `offset + limit + 1 <= 10000` (e.g. 9899 with limit 100); page with `cursor` or narrow the search to go deeper", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Principal not entitled to the bound tenant, or a machine principal missing axs:ingest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "503": { "description": "The reporting status overlay (locally blocked reports) could not be read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List and search the tenant's documents (read-model)", "tags": [ "documents" ] } }, "/audit": { "get": { "description": "Returns a newest-first, filtered seq-cursor page of the tenant's tamper-evident audit chain (§16.2.1 PASR). The actor filter matches actor id or the tenant user name/email projection; date filters accept ISO timestamps or YYYY-MM-DD UTC days. Supports action-prefix/resource/outcome filters and an `after` cursor. Requires a human principal carrying the `auditor` RBAC role, or a machine principal carrying the `axs:audit-read` scope, and the `x-tenant-id` header bound to the owning tenant.", "operationId": "AuditController_list", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "action", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "actor", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "resource", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "outcome", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "from", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "to", "required": false, "in": "query", "schema": { "type": "string" } }, { "name": "after", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditPageDto" } } } }, "400": { "description": "Missing/invalid x-tenant-id, or a malformed query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Principal not entitled: human without the auditor role, machine without the axs:audit-read scope, or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List/search audit records (auditor)", "tags": [ "audit" ] } }, "/audit/verify": { "get": { "description": "Recomputes verifyChain (@axs/audit) over the tenant's full stored chain — a real integrity recompute, not a cached flag — and reports the latest signed Merkle checkpoint, if any. Requires a human principal carrying the `auditor` RBAC role, or a machine principal carrying the `axs:audit-read` scope, and the `x-tenant-id` header bound to the owning tenant.", "operationId": "AuditController_verify", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditVerifyDto" } } } }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Principal not entitled: human without the auditor role, machine without the axs:audit-read scope, or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Verify the tenant audit chain + latest checkpoint (auditor)", "tags": [ "audit" ] } }, "/audit/legal-hold": { "post": { "description": "Creates an active legal hold over the tenant audit trail (§17.5): while a hold overlaps an audit_log partition range, that partition is never dropped by retention. Open-ended when fromOccurredAt/toOccurredAt are omitted. The creation itself is audit-logged, fail-closed. Requires a human principal carrying the `auditor` RBAC role.", "operationId": "AuditLegalHoldController_create", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLegalHoldDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldDto" } } } }, "400": { "description": "Malformed body (incl. fromOccurredAt after toOccurredAt) or tenant header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Principal not entitled: machine principal on a human-only surface, human without the auditor role, or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "holdId already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a legal hold (auditor)", "tags": [ "audit" ] }, "get": { "description": "Lists the tenant's active legal holds. Requires a human principal carrying the `auditor` RBAC role.", "operationId": "AuditLegalHoldController_list", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldListDto" } } } }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Principal not entitled: machine principal on a human-only surface, human without the auditor role, or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List active legal holds (auditor)", "tags": [ "audit" ] } }, "/audit/legal-hold/{holdId}": { "delete": { "description": "Soft-releases a hold (active=false) — the row is never deleted (audit posture). The release itself is audit-logged, fail-closed. Requires a human principal carrying the `auditor` RBAC role.", "operationId": "AuditLegalHoldController_release", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "holdId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegalHoldReleasedDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Principal not entitled: machine principal on a human-only surface, human without the auditor role, or tenant mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "No active hold with this id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Release a legal hold (auditor)", "tags": [ "audit" ] } }, "/documents/{integrationId}/ubl": { "get": { "description": "Returns the UBL + SBDH XML for a document: the exact stored wire artifact if the egress run produced one, otherwise a deterministic re-render from the durable canonical payload (`source` distinguishes the two — the re-render is a representation, not the byte-authoritative compliance copy).", "operationId": "DocumentReadController_getUbl", "parameters": [ { "name": "integrationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactResponseDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Download the document artifact (stored wire copy or re-render)", "tags": [ "ingest" ] } }, "/documents/{integrationId}/pdf": { "get": { "description": "Renders a representation PDF from the durable canonical payload (never the byte-authoritative compliance copy). 404 if no payload exists, 422 if rendering fails.", "operationId": "DocumentReadController_getPdf", "parameters": [ { "name": "integrationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "application/pdf bytes" }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Download a human-readable PDF rendering of the document", "tags": [ "ingest" ] } }, "/documents/{integrationId}/invoice": { "get": { "description": "Returns the durable canonical invoice exactly as admitted at ingest — the portal invoice-view reads this. Always a representation, never the byte-authoritative compliance copy (the WORM-anchored wire artifact remains authoritative). 404 if no payload exists for the document.", "operationId": "DocumentReadController_getInvoice", "parameters": [ { "name": "integrationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoredInvoiceDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Read the full canonical invoice payload (header + lines + parties)", "tags": [ "ingest" ] } }, "/documents/{integrationId}/resend": { "post": { "description": "CAS-resets a stuck `outbound_dispatch` row (status FAILED or QUARANTINED) back to PENDING so the existing EgressDispatcher re-picks it on its next tick; a SENT/PENDING/ DISPATCHING row is not resettable (409). The action is best-effort audited (`document.resend.requested`) with the row's previous status.", "operationId": "DocumentReadController_resend", "parameters": [ { "name": "integrationId", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendResultDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Machine principal, read-only role (auditor), or tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Self-service resend: reset a FAILED/QUARANTINED dispatch row to PENDING", "tags": [ "ingest" ] } }, "/onboarding/participants": { "post": { "description": "Idempotent register-then-map (design §5): upserts a PENDING onboarding row, registers the participant with the SMP — or, when it is already published by us, rewrites the SMP record with a full-replacement update (AXS-113) — then commits REGISTERED + the participant_registry routing mapping in one transaction. A re-provision on an already-REGISTERED participant bumps the registration data version and re-syncs the SMP; PUT /onboarding/participants/{scheme}/{value} is the dedicated capability update.", "operationId": "OnboardingController_provision", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingStatusDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "Invalid participant id (`participant-id`), refused TIN (`tin-verification`, `tax-group-representative-tin`) or malformed body (`envelope-shape`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingViolationsDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Provision (or re-provision) a participant into the SMP + registry", "tags": [ "onboarding" ] } }, "/onboarding/participants/{scheme}/{value}": { "get": { "description": "Reads the current onboarding status (NONE/PENDING/REGISTERED/DELISTED) and registration data for a participant identifier under the bound tenant; NONE (with null fields) when no onboarding row exists yet.", "operationId": "OnboardingController_status", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "scheme", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "value", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingStatusDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "Invalid participant id (`participant-id`), refused TIN (`tin-verification`, `tax-group-representative-tin`) or malformed body (`envelope-shape`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingViolationsDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Onboarding status of a participant", "tags": [ "onboarding" ] }, "put": { "description": "Full replacement of the published registration (endpoint, document profiles, business card) — the SMP PUT is not a patch, so send every field. Only a REGISTERED participant is updatable (400 otherwise); the SMP is rewritten FIRST, then the stored data (stays REGISTERED, bumps regDataVersion), audited as `participant.updated`. 409 when the publication is foreign-owned or no longer on the SMP (reconcile/re-provision first); 502 when the SMP refused the write.", "operationId": "OnboardingController_update", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "scheme", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "value", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRegistrationDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingStatusDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "Invalid participant id (`participant-id`), refused TIN (`tin-verification`, `tax-group-representative-tin`) or malformed body (`envelope-shape`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingViolationsDto" } } } }, "502": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update a registered participant's SMP capabilities (AXS-113, T3.3)", "tags": [ "onboarding" ] }, "delete": { "description": "Unmap-then-delist (design §5): removes the participant_registry routing mapping BEFORE delisting from the SMP, then marks the onboarding row DELISTED (the lifecycle machine decides the terminal status). Then MEASURES the propagation (AXS-113): an SMP read-back and an SML NAPTR probe, reported as `propagation` and audited — it never rolls back. Requires an existing onboarding row (404 otherwise).", "operationId": "OnboardingController_delist", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "scheme", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "value", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelistResultDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "Invalid participant id (`participant-id`), refused TIN (`tin-verification`, `tax-group-representative-tin`) or malformed body (`envelope-shape`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingViolationsDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Delist a participant (unmap routing, then SMP delist)", "tags": [ "onboarding" ] } }, "/onboarding/participants/{scheme}/{value}/reconcile": { "post": { "description": "Looks up the participant on the SMP and compares it against the stored onboarding status (drift: true when a REGISTERED row is no longer published, or vice versa); touches lastReconciledAt and audit-logs the check. Also re-measures the SML NAPTR leg (smlPublished) — the way to confirm a `sml-pending` delist later. Requires an existing onboarding row (404 otherwise).", "operationId": "OnboardingController_reconcile", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "scheme", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "value", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconcileResultDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "Invalid participant id (`participant-id`), refused TIN (`tin-verification`, `tax-group-representative-tin`) or malformed body (`envelope-shape`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingViolationsDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "On-demand SMP drift check for a participant", "tags": [ "onboarding" ] } }, "/registration-request": { "post": { "description": "Signals the operator that the company selected this service provider in EmaraTax and needs its 0235 participant (TIN = first 10 TRN digits) registered. Does not register anything itself and never submits invoices. 422 when the company profile or TRN is missing or the EmaraTax confirmation is absent; 409 when a request is already open or the participant is already registered.", "operationId": "RegistrationRequestController_create", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationRequestBodyDto" } } } }, "responses": { "201": { "description": "Request opened", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationViewDto" } } } }, "401": { "description": "Missing/invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Machine principal, read-only role (auditor), or tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "Already open or already registered" }, "422": { "description": "Validation violations" } }, "security": [ { "bearer": [] } ], "summary": "Request Peppol registration of the company participant (human-only, audited)", "tags": [ "profile" ] } }, "/dashboard/summary": { "get": { "description": "Composes the §8 CQRS search read-model KPI aggregation (today's volume by direction, outcome counts, C5 report-status summary) with the tenant free-tier consumption counter. Eventually consistent; short-cached. Requires a valid Bearer token and the `x-tenant-id` header bound to the owning tenant.", "operationId": "DashboardController_summary", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant-scoped KPI summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardSummaryDto" } } } }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Principal not entitled to the bound tenant, or a machine principal missing axs:ingest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "The tenant's portal home KPIs (read-model + free-tier)", "tags": [ "dashboard" ] } }, "/dashboard/onboarding": { "get": { "description": "Derives profile, active partner, active product and issued outbound invoice completion from tenant-scoped server records. Browser storage and Peppol activation are not inputs.", "operationId": "DashboardController_onboardingChecklist", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingChecklistDto" } } } }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "The tenant's server-derived onboarding checklist", "tags": [ "dashboard" ] } }, "/dashboard/onboarding/guide": { "get": { "description": "Returns `not-started` until the user starts, skips or finishes the guided flow. A preference per tenant and user; never a completion input.", "operationId": "OnboardingGuideController_get", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingGuideDto" } } } }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Tenant not entitled or machine principal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "The signed-in user's guided-setup decision in this tenant (human-only)", "tags": [ "dashboard" ] }, "put": { "description": "Upserts the decision for the bound tenant and the signed-in user and writes a metadata-only audit record in the same transaction.", "operationId": "OnboardingGuideController_put", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingGuideBodyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingGuideDto" } } } }, "403": { "description": "Machine principal, read-only role (auditor), or tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "Unknown status or unexpected field" } }, "security": [ { "bearer": [] } ], "summary": "Record starting, skipping or finishing the guided setup (human-only)", "tags": [ "dashboard" ] } }, "/reference/currencies": { "get": { "description": "Returns the ISO 4217 active currency codes served from `@axs/reference`. Global reference data, not tenant-scoped — requires a valid bearer token only.", "operationId": "ReferenceController_currencies", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyListDto" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "ISO 4217 currency reference list", "tags": [ "reference" ] } }, "/reference/countries": { "get": { "description": "Returns the ISO 3166-1 alpha-2 country codes served from `@axs/reference`. Global reference data, not tenant-scoped — requires a valid bearer token only.", "operationId": "ReferenceController_countries", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryListDto" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "ISO 3166-1 alpha-2 country reference list", "tags": [ "reference" ] } }, "/notifications": { "get": { "description": "Returns a cursor-paged page of the notification bell-list plus the current unread count, both read from the durable tenant-scoped `notification` table (ADR-0053). Requires a valid Bearer token and the `x-tenant-id` header bound to the owning tenant.", "operationId": "NotificationController_list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "Opaque before-cursor (the last item id of the previous page).", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Page size, clamped to 1–100 (default 25).", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant-scoped notification page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPageDto" } } } }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Not entitled / missing axs:ingest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List the tenant's in-app notifications (paged) + unread count", "tags": [ "notifications" ] }, "delete": { "description": "Hard-deletes every notification of the bound tenant (ADR-0054, the bell panel's 'delete all' header action). Requires a valid Bearer token and the `x-tenant-id` header bound to the owning tenant.", "operationId": "NotificationController_removeAll", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "All notifications deleted" }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Read-only role (auditor) or tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Delete all of the tenant's notifications (hard-delete)", "tags": [ "notifications" ] } }, "/notifications/read": { "post": { "description": "Marks the given notification ids read for the bound tenant, or every unread notification when `ids` is omitted/empty. Requires a valid Bearer token and the `x-tenant-id` header bound to the owning tenant.", "operationId": "NotificationController_markRead", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkReadDto" } } } }, "responses": { "200": { "description": "Marked read" }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Mark notifications read (ids, or all when omitted)", "tags": [ "notifications" ] } }, "/notifications/{id}": { "delete": { "description": "Hard-deletes the given notification for the bound tenant (ADR-0054). Idempotent: an unknown id still returns 200 — after a delete, a later reopen→re-terminal transition may legitimately create a new notification for the same document+type. Requires a valid Bearer token and the `x-tenant-id` header bound to the owning tenant.", "operationId": "NotificationController_remove", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted (or did not exist)" }, "400": { "description": "Missing/invalid x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Read-only role (auditor) or tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Delete one notification (hard-delete, idempotent)", "tags": [ "notifications" ] } }, "/profile": { "get": { "description": "Reads the durable tenant_profile row (seller identity backing invoice emission) and derives the Peppol registration from the TRN's first 10 digits (portal TRN→TIN convention) compared with the tenant's own participant registry rows: peppolRegistration.status is registered (the derived participant is one of them), mismatch (the tenant has participants, but not the derived one) or none. participantRegistered is deprecated and equals status === registered. Returns profile: null, participantRegistered: false and peppolRegistration.status none (derivedParticipantId null; registeredParticipantIds still lists the own rows) when the tenant has not yet set a profile. Requires a valid Bearer token and the x-tenant-id header bound to the owning tenant.", "operationId": "ProfileController_get", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Profile (null if unset)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponseDto" } } } }, "400": { "description": "Missing x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Get the tenant's company profile (seller identity) + SMP registration status", "tags": [ "profile" ] }, "put": { "description": "Upserts the tenant_profile row (seller identity) and returns the same shape as GET /profile. Human-only (RequireHumanGuard rejects a machine/OAuth2-CC principal with 403) and atomically writes a profile.updated audit record on success. A malformed TRN or other body violation returns 422 {violations}, never a 500. Requires a valid Bearer token and the x-tenant-id header bound to the owning tenant.", "operationId": "ProfileController_put", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileBodyDto" } } } }, "responses": { "200": { "description": "Upserted profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponseDto" } } } }, "401": { "description": "Missing/invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Machine principal, read-only role (auditor), or tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "Validation violations (English `message`; branch on `rule`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MasterDataViolationsDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create or update the tenant's company profile (human-only, audited)", "tags": [ "profile" ] } }, "/invoice-drafts": { "get": { "description": "Returns paginated summaries within the entitled active tenant, without invoice form contents.", "operationId": "InvoiceDraftController_list", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "offset", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDraftPageDto" } } } }, "422": { "description": "Invalid paging" } }, "security": [ { "bearer": [] } ], "summary": "List manually saved invoice drafts, newest first (human-only)", "tags": [ "invoice-drafts" ] } }, "/invoice-drafts/{id}": { "get": { "description": "Returns versioned editor state. Missing or removed drafts in this tenant return 404.", "operationId": "InvoiceDraftController_get", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDraftDto" } } } }, "404": { "description": "Draft not found in this tenant" } }, "security": [ { "bearer": [] } ], "summary": "Read an incomplete draft (human-only)", "tags": [ "invoice-drafts" ] }, "put": { "description": "Persists an explicit manual save without validation or submission. A stale version returns 409; form contents are limited to 256 KiB.", "operationId": "InvoiceDraftController_put", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDraftBodyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDraftDto" } } } }, "403": { "description": "Machine principal, read-only role (auditor), or tenant not entitled" }, "409": { "description": "Stale version, removed draft or id already used" }, "422": { "description": "Invalid draft body; form maximum 256 KiB" } }, "security": [ { "bearer": [] } ], "summary": "Save an incomplete form without issuing it; version 0 creates, otherwise compare-and-swap", "tags": [ "invoice-drafts" ] }, "delete": { "description": "Requires the current draft version. Stale or missing drafts return 409; old create retries cannot resurrect a removed draft.", "operationId": "InvoiceDraftController_remove", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "version", "required": true, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDraftDeletedDto" } } } }, "403": { "description": "Machine principal, read-only role (auditor), or tenant not entitled" }, "409": { "description": "Draft changed or no longer available" }, "422": { "description": "Invalid version" } }, "security": [ { "bearer": [] } ], "summary": "Remove a saved draft with an optimistic version check (soft deletion)", "tags": [ "invoice-drafts" ] } }, "/invoice-number-series": { "get": { "description": "Active series first. A series binds a pattern, document kinds and an optional yearly restart; it numbers invoices issued manually in the portal only — integrations number their own invoices.", "operationId": "NumberSeriesController_list", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberSeriesListDto" } } } }, "401": { "description": "Missing/invalid bearer token" }, "403": { "description": "Machine principal, tenant not entitled, or (writes) not a tenant-admin" } }, "security": [ { "bearer": [] } ], "summary": "List the tenant invoice number series (portal manual issuance, human-only)", "tags": [ "invoice-number-series" ] }, "post": { "description": "The pattern, document kinds and yearly restart are fixed after creation (traceability); to change them, deactivate the series and define a new one. A yearly restart requires {YYYY} in the pattern so that every number stays unique.", "operationId": "NumberSeriesController_create", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNumberSeriesDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberSeriesDto" } } } }, "401": { "description": "Missing/invalid bearer token" }, "403": { "description": "Machine principal, tenant not entitled, or (writes) not a tenant-admin" }, "409": { "description": "Another series of this tenant has the same pattern" }, "422": { "description": "Invalid name, pattern or document kinds" } }, "security": [ { "bearer": [] } ], "summary": "Define an invoice number series (tenant-admin)", "tags": [ "invoice-number-series" ] } }, "/invoice-number-series/{id}": { "patch": { "description": "Only the name and the active flag change. A deactivated series is no longer suggested and an issuance that still names it is refused (422 NUMBER_SERIES_UNAVAILABLE); its allocation log stays readable.", "operationId": "NumberSeriesController_update", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNumberSeriesDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberSeriesDto" } } } }, "401": { "description": "Missing/invalid bearer token" }, "403": { "description": "Machine principal, tenant not entitled, or (writes) not a tenant-admin" }, "404": { "description": "No such series in this tenant" }, "422": { "description": "Empty or invalid patch" } }, "security": [ { "bearer": [] } ], "summary": "Rename or (de)activate an invoice number series (tenant-admin)", "tags": [ "invoice-number-series" ] } }, "/invoice-number-series/{id}/next": { "get": { "description": "The number is consumed only when the invoice is issued (POST /ingest with numberSeries), inside the issuing transaction. Numbers already taken in this tenant are skipped.", "operationId": "NumberSeriesController_next", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "issueDate", "required": true, "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberSeriesNextDto" } } } }, "401": { "description": "Missing/invalid bearer token" }, "403": { "description": "Machine principal, tenant not entitled, or (writes) not a tenant-admin" }, "404": { "description": "No active series with this id in this tenant" }, "422": { "description": "Missing or malformed issueDate" } }, "security": [ { "bearer": [] } ], "summary": "Suggest the next free number of a series for an issue date (reserves nothing)", "tags": [ "invoice-number-series" ] } }, "/invoice-number-series/{id}/allocations": { "get": { "description": "Every consumed sequence number has exactly one row: issued (with its document) or skipped (the number was already taken in this tenant). A manual override records the number the issuer typed and the number that was suggested.", "operationId": "NumberSeriesController_allocations", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "offset", "required": false, "in": "query", "schema": { "type": "number" } }, { "name": "limit", "required": false, "in": "query", "schema": { "type": "number" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberSeriesAllocationPageDto" } } } }, "401": { "description": "Missing/invalid bearer token" }, "403": { "description": "Machine principal, tenant not entitled, or (writes) not a tenant-admin" }, "422": { "description": "Invalid paging" } }, "security": [ { "bearer": [] } ], "summary": "The allocation log of a series, newest first (issued, skipped, manual override)", "tags": [ "invoice-number-series" ] } }, "/partners": { "get": { "description": "Returns the tenant partner directory. An empty q orders by last used first (the invoice-create picker relies on this), otherwise filters name and TRN case- and accent-insensitively. Inactive (soft-deleted) partners are hidden unless includeInactive=true.", "operationId": "PartnerController_list", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Page size (default 25, capped at 100).", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Row offset for paging (default 0, no upper bound).", "schema": { "type": "number" } }, { "name": "includeInactive", "required": false, "in": "query", "description": "Include soft-deactivated partners (default false).", "schema": { "type": "boolean" } }, { "name": "q", "required": false, "in": "query", "description": "Case-/accent-insensitive search over name and TRN.", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Partner page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerPageDto" } } } }, "400": { "description": "Missing x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List the tenant's partners (search, paging)", "tags": [ "partners" ] }, "post": { "description": "A partner with no TRN is accepted on purpose — a counterparty outside the Peppol network is a legitimate directory entry (design D3). A TRN already used by another partner of this tenant returns 409 with the existing id.", "operationId": "PartnerController_create", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerBodyDto" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerDto" } } } }, "403": { "description": "Machine principal, read-only role (auditor), or tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "Duplicate TRN", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerConflictDto" } } } }, "422": { "description": "Validation violations (English `message`; branch on `rule`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MasterDataViolationsDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a partner (human-only, audited)", "tags": [ "partners" ] } }, "/partners/{id}": { "get": { "description": "Reads a single partner by id, including a soft-deactivated one.", "operationId": "PartnerController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerDto" } } } }, "404": { "description": "No such partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Read one partner", "tags": [ "partners" ] }, "put": { "description": "Replaces the partner fields (full-body PUT, no partial patch). Same TRN-shape validation as create; a not-found id returns 404.", "operationId": "PartnerController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerBodyDto" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerDto" } } } }, "403": { "description": "Machine principal, read-only role (auditor), or tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "No such partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "Validation violations (English `message`; branch on `rule`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MasterDataViolationsDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update a partner (human-only, audited)", "tags": [ "partners" ] }, "delete": { "description": "Soft delete: the row stays so an already-issued invoice never loses its counterparty record (design D7). The partner disappears from the pickers.", "operationId": "PartnerController_deactivate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deactivated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerDeactivatedDto" } } } }, "403": { "description": "Machine principal, read-only role (auditor), or tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "No such partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Deactivate a partner (human-only, audited)", "tags": [ "partners" ] } }, "/partners/{id}/used": { "post": { "description": "Writes last_used_at so the picker can offer recently invoiced partners first (design D8). Not audited — it carries no content change.", "operationId": "PartnerController_used", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Recorded" }, "403": { "description": "Read-only role (auditor) or tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "No such partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Mark a partner as just used (ordering hint)", "tags": [ "partners" ] } }, "/partners/{id}/peppol/verify": { "post": { "description": "Runs the server-side SMP verification and persists only an available result. An unavailable lookup leaves the last trusted partner status unchanged. A concurrent TRN edit returns 409 rather than attaching the old verification result to the new partner identity.", "operationId": "PartnerController_reverifyPeppol", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolVerifyDto" } } } }, "403": { "description": "Machine principal or read-only role (auditor)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "No such partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "Partner TRN changed while verification was in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "The partner has no TRN to verify", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Reverify a partner's stored TRN (human-only, audited)", "tags": [ "partners" ] } }, "/peppol/verify": { "get": { "description": "Resolves the TRN to its 0235 participant id and asks the SMP. The answer is cached for 24h and guarded by a circuit breaker: when the lookup is down the endpoint returns available=false (with the last known answer marked stale) instead of failing — this is a convenience signal, not a compliance gate.", "operationId": "PeppolController_verify", "parameters": [ { "name": "trn", "required": true, "in": "query", "description": "The 15-digit TRN to check.", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolVerifyDto" } } } }, "401": { "description": "Missing/invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "Missing, repeated or malformed TRN (`violations[0].rule` = `INVALID_TRN`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeppolVerifyViolationsDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Check whether a TRN is registered in the Peppol network", "tags": [ "peppol" ] } }, "/products": { "get": { "description": "Returns the tenant product catalogue. An empty q orders by last used first (the invoice-create line picker relies on this), otherwise filters name and SKU case- and accent-insensitively. Inactive (soft-deleted) products are hidden unless includeInactive=true.", "operationId": "ProductController_list", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Page size (default 25, capped at 100).", "schema": { "type": "number" } }, { "name": "offset", "required": false, "in": "query", "description": "Row offset for paging (default 0, no upper bound).", "schema": { "type": "number" } }, { "name": "includeInactive", "required": false, "in": "query", "description": "Include soft-deactivated products (default false).", "schema": { "type": "boolean" } }, { "name": "q", "required": false, "in": "query", "description": "Case-/accent-insensitive search over name and SKU.", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductPageDto" } } } }, "400": { "description": "Missing x-tenant-id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "Missing/invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List the tenant's products (search, paging)", "tags": [ "products" ] }, "post": { "description": "A product with no SKU is accepted on purpose (design P1) — only the name is required. A SKU already used by another product of this tenant (case-insensitively, design P4) returns 409 with the existing id.", "operationId": "ProductController_create", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductBodyDto" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDto" } } } }, "403": { "description": "Machine principal, read-only role (auditor), or tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "Duplicate SKU", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductConflictDto" } } } }, "422": { "description": "Validation violations (English `message`; branch on `rule`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MasterDataViolationsDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a product (human-only, audited)", "tags": [ "products" ] } }, "/products/{id}": { "get": { "description": "Reads a single product by id, including a soft-deactivated one.", "operationId": "ProductController_get", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDto" } } } }, "404": { "description": "No such product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Read one product", "tags": [ "products" ] }, "put": { "description": "Replaces the product fields (full-body PUT, no partial patch). The VAT rate is derived from the category, never taken from the body. A not-found id returns 404.", "operationId": "ProductController_update", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductBodyDto" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDto" } } } }, "403": { "description": "Machine principal, read-only role (auditor), or tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "No such product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "Validation violations (English `message`; branch on `rule`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MasterDataViolationsDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update a product (human-only, audited)", "tags": [ "products" ] }, "delete": { "description": "Soft delete: the row stays so an already-issued invoice never loses its line reference (design D7). The product disappears from the pickers and its SKU stays taken.", "operationId": "ProductController_deactivate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deactivated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDeactivatedDto" } } } }, "403": { "description": "Machine principal, read-only role (auditor), or tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "No such product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Deactivate a product (human-only, audited)", "tags": [ "products" ] } }, "/products/{id}/used": { "post": { "description": "Writes last_used_at so the picker can offer recently invoiced products first (design D8). Not audited — it carries no content change.", "operationId": "ProductController_used", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Recorded" }, "403": { "description": "Read-only role (auditor) or tenant not entitled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "No such product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Mark a product as just used (ordering hint)", "tags": [ "products" ] } }, "/api-clients": { "get": { "description": "Returns every machine client (active, unfinished and revoked) with its purpose, scopes and lifecycle timestamps, plus the tenant quota counters. Never returns a secret — a client secret is shown exactly once, at creation or rotation.", "operationId": "ApiClientsController_list", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientListDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List the machine clients of the bound tenant", "tags": [ "api-clients" ] }, "post": { "description": "Derives a deterministic client id from the display name, provisions a confidential client-credentials client in Keycloak with the AXS shape invariant, and returns the secret ONCE. The secret is never stored and can never be retrieved again — only rotated.", "operationId": "ApiClientsController_create", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiClientBodyDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientSecretDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "Validation violations" }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a machine client (OAuth2 client-credentials)", "tags": [ "api-clients" ] } }, "/api-clients/{clientId}/rotate": { "post": { "description": "Regenerates the Keycloak client secret and returns the new value ONCE. The old secret stops working immediately, so the ERP integration must be reconfigured. Only an active client can be rotated (409 otherwise).", "operationId": "ApiClientsController_rotate", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientSecretDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Rotate the client secret", "tags": [ "api-clients" ] } }, "/api-clients/{clientId}/resume": { "post": { "description": "Completes a client left in PENDING by an interrupted creation (the Keycloak call failed or the process died between the call and the commit). Re-runs the Keycloak provisioning idempotently and returns a fresh secret ONCE. Only a PENDING client can be resumed.", "operationId": "ApiClientsController_resume", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientSecretDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Finish an interrupted provisioning", "tags": [ "api-clients" ] } }, "/api-clients/{clientId}": { "delete": { "description": "Disables the client in Keycloak FIRST (access stops immediately), then marks the row REVOKED. The row and the client id are kept, not deleted, so the audit trail stays intact and the id is never reissued.", "operationId": "ApiClientsController_revoke", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "clientId", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiClientDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Revoke a machine client", "tags": [ "api-clients" ] } }, "/tenant-users": { "get": { "description": "Every user (pending/invited/active/disabled) plus the live tenant-admin count.", "operationId": "TenantUsersController_list", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserListDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "List the human users of the bound tenant", "tags": [ "tenant-users" ] }, "post": { "description": "Creates+e-mails an invite, or links an existing realm account (linked:true, no e-mail).", "operationId": "TenantUsersController_invite", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteTenantUserBodyDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserInviteResultDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserConflictDto" } } } }, "422": { "description": "Validation violations" }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserUnavailableDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Invite (or link) a tenant user", "tags": [ "tenant-users" ] } }, "/tenant-users/{id}/resend": { "post": { "description": "Re-sends the password-set e-mail for a user still awaiting activation.", "operationId": "TenantUsersController_resend", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserConflictDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserUnavailableDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Resend the invitation e-mail", "tags": [ "tenant-users" ] } }, "/tenant-users/{id}/resume": { "post": { "description": "Re-runs a PENDING invite's Keycloak step idempotently (an orphan account is linked, not duplicated).", "operationId": "TenantUsersController_resume", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserConflictDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserUnavailableDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Finish an interrupted invitation", "tags": [ "tenant-users" ] } }, "/tenant-users/{id}/role": { "put": { "description": "Replaces the Keycloak role mapping (old role removed first). Refused for the last admin.", "operationId": "TenantUsersController_changeRole", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeTenantUserRoleBodyDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserConflictDto" } } } }, "422": { "description": "Validation violations" }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserUnavailableDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Change a tenant user's role", "tags": [ "tenant-users" ] } }, "/tenant-users/{id}": { "delete": { "description": "Disables in Keycloak first, then marks DISABLED. Deactivation, never deletion — except a PENDING row (no Keycloak account yet), which is removed outright (AXS-238).", "operationId": "TenantUsersController_disable", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserConflictDto" } } } }, "422": { "description": "Validation violations" }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserUnavailableDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Disable a tenant user (or remove an unfinished invitation)", "tags": [ "tenant-users" ] } }, "/tenant-users/{id}/enable": { "post": { "description": "Re-enables in Keycloak; the mirror goes ACTIVE if a password was ever set, else INVITED.", "operationId": "TenantUsersController_enable", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserConflictDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserUnavailableDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Re-enable a disabled tenant user", "tags": [ "tenant-users" ] } }, "/tenant-users/{id}/reconcile": { "post": { "description": "Keycloak wins on drift. Fail-safe — a Keycloak outage is a no-op, never a throw.", "operationId": "TenantUsersController_reconcile", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantUserDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Reconcile the mirror row against Keycloak", "tags": [ "tenant-users" ] } }, "/callbacks": { "get": { "description": "Human tenant-admin only. Returns the current target and version; never returns a signing secret.", "operationId": "CallbackController_get", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackConfigDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Read the tenant callback configuration without secrets", "tags": [ "callbacks" ] }, "put": { "description": "Human tenant-admin only. HTTPS port 443, public IPv4 DNS only; no credentials, query, fragment, redirects. New/rotated secret is returned once. Changing the configuration cancels pending deliveries; historical payloads are never retargeted. Receivers verify HMAC-SHA256(timestamp + dot + exact body), reject stale timestamps and deduplicate x-axs-event-id. Delivery is at-least-once.", "operationId": "CallbackController_put", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackUpdateDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackSavedDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Configure HTTPS HMAC callbacks and optionally rotate the secret", "tags": [ "callbacks" ] } }, "/callbacks/deliveries": { "get": { "description": "Human tenant-admin only. Lists this tenant’s event status, attempts and delivery evidence without secret material.", "operationId": "CallbackController_deliveries", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackDeliveryListDto" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Read the most recent 100 audited delivery statuses", "tags": [ "callbacks" ] } }, "/callbacks/deliveries/{id}/retry": { "post": { "description": "Idempotent while pending, retrying, delivered or cancelled. Only DEAD starts a new six-attempt budget. Event id and payload stay unchanged; recipients must deduplicate.", "operationId": "CallbackController_retry", "parameters": [ { "name": "x-tenant-id", "in": "header", "description": "Tenant identifier binding the request to a tenant.", "required": true, "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "503": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Retry an exhausted event to its unchanged configured target", "tags": [ "callbacks" ] } }, "/ready": { "get": { "description": "Checks the dependencies required to accept and forward a document (database, queue, outbound transport). Returns 200 when all are usable and 503 otherwise. No authentication required — this is the measurement point of the availability control (T6.8).", "operationId": "ReadinessController_ready", "parameters": [], "responses": { "200": { "description": "All required components are usable." }, "503": { "description": "At least one required component is unusable." } }, "summary": "Deep readiness probe", "tags": [ "system" ] } }, "/me": { "get": { "description": "Returns the principal decoded from the bearer token. Requires a valid `Authorization: Bearer ` (401 if missing or invalid). Use it to verify the auth path end to end.", "operationId": "MeController_me", "parameters": [], "responses": { "200": { "description": "The authenticated principal." }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Return the authenticated principal", "tags": [ "identity" ] } }, "/me/profile": { "get": { "description": "Returns the display name, e-mail, roles and company memberships of the account behind the bearer token, reading the name from the identity provider so a change made elsewhere is visible immediately. Roles, memberships and the e-mail are read-only here (`emailEditable` is always false). When the identity plane is unreachable the response degrades to the verified token claims with `nameEditable: false` instead of failing, so the user still sees who they are signed in as. No tenant header is used.", "operationId": "MeController_profile", "parameters": [], "responses": { "200": { "description": "The own profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeProfileDto" } } } }, "401": { "description": "Missing/invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Machine principal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Read the signed-in user's own profile (human-only)", "tags": [ "identity" ] }, "put": { "description": "Writes `firstName`/`lastName` to the identity provider for the account behind the bearer token and returns the refreshed own profile. Only those two fields are accepted: roles, company membership and the e-mail cannot be changed on this route and any extra property is rejected with 422 {violations}. Passwords and two-factor settings never travel through this API — the portal starts a Keycloak required-action redirect for those. Every attempt writes a `me.profile.updated` audit record. Returns 503 when the identity plane is unreachable, never a silent success.", "operationId": "MeController_updateProfile", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMeProfileBodyDto" } } } }, "responses": { "200": { "description": "The refreshed own profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeProfileDto" } } } }, "401": { "description": "Missing/invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Machine principal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "`{violations: [{rule, path, message}]}` — one channel for both sources that can reject a name: our own rules (`NAME_REQUIRED`, `NAME_TOO_LONG`, `NAME_PROHIBITED_CHARACTERS`, `NAME_CONTROL_CHARACTERS`, `UNKNOWN_FIELD`) and the identity provider, whose own user-profile validation is mapped onto the same rule codes (`NAME_REJECTED` when its reason is not one we know). `path` is the field name (`firstName`/`lastName`), empty when the provider named no field. Decide on `rule`, show `message` as detail: it is raw English, never localized." }, "503": { "description": "`{error, rule: \"KC_UNAVAILABLE\"}` — the identity plane could not be reached, so the name was NOT written. Distinct from 422: retrying later can succeed unchanged." } }, "security": [ { "bearer": [] } ], "summary": "Update the signed-in user's own display name (human-only, audited)", "tags": [ "identity" ] } }, "/me/tenant-preference": { "get": { "description": "Returns the company the account behind the bearer token last selected in the portal. `lastTenantId` is null when nothing is stored or the user is no longer a member of the stored company. Keyed by the token subject only; no tenant header is used.", "operationId": "TenantPreferenceController_read", "parameters": [], "responses": { "200": { "description": "The stored preference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPreferenceDto" } } } }, "401": { "description": "Missing/invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Machine principal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } } }, "security": [ { "bearer": [] } ], "summary": "Read the company the signed-in user last switched to (human-only)", "tags": [ "identity" ] }, "put": { "description": "Stores `tenantId` as the account’s last selected company. The company must be one of the memberships in the bearer token (403 otherwise). The body accepts only `tenantId`; any other property is rejected with 422 {violations}.", "operationId": "TenantPreferenceController_update", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTenantPreferenceBodyDto" } } } }, "responses": { "200": { "description": "The stored preference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPreferenceDto" } } } }, "401": { "description": "Missing/invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "403": { "description": "Machine principal, or the company is not one of the token memberships", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelopeDto" } } } }, "422": { "description": "`{violations: [{rule, path, message}]}`" } }, "security": [ { "bearer": [] } ], "summary": "Remember the company the signed-in user switched to (human-only)", "tags": [ "identity" ] } } }, "info": { "title": "AXS API", "description": "AXS — UAE Peppol e-invoicing ASP platform. See docs/api/getting-started.md.", "version": "1.1.0", "contact": { "name": "AXS", "url": "https://spartancode.hu", "email": "support@spartancode.hu" } }, "tags": [ { "name": "ingest", "description": "Submit invoices and track document legs" }, { "name": "identity", "description": "Authenticated principal" }, { "name": "system", "description": "Liveness and service info" } ], "servers": [ { "url": "/", "description": "Current API origin" } ], "components": { "securitySchemes": { "bearer": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http" } }, "schemas": { "ErrorEnvelopeDto": { "type": "object", "properties": { "statusCode": { "type": "number" }, "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" }, "path": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "statusCode", "error", "message", "requestId", "path", "timestamp" ] }, "IngestDto": { "type": "object", "properties": { "sbdh": { "type": "object", "properties": { "sender": { "type": "string" }, "receiver": { "type": "string" } }, "required": [ "sender", "receiver" ] }, "invoice": { "type": "object", "properties": { "id": { "type": "string" }, "uuid": { "type": "string" }, "issueDate": { "type": "string" }, "documentKind": { "type": "string" }, "billingMode": { "type": "string" }, "typeCode": { "type": "string" }, "currencyCode": { "type": "string" }, "exchangeRate": { "type": "string" }, "transactionTypeCode": { "type": "string" }, "paymentDueDate": { "type": "string" }, "taxPointDate": { "type": "string" }, "businessProcessType": { "type": "string" }, "specificationIdentifier": { "type": "string" }, "paymentMeansTypeCode": { "description": "Payment means type code (IBT-081), mandatory. Closed list — PINT AE publishes its own UNCL4461 subset, \"Payment means codes used in AE\": 1 instrument not defined, 10 in cash, 20 cheque, 21 banker's draft, 30 credit transfer, 49 direct debit, 54 credit card, 55 debit card, 68 online payment service. Any other value is rejected with 422 INVALID_PAYMENT_MEANS_CODE naming the acceptable codes, including UNCL4461 codes such as 48 that the Schematron would take but the AE list does not contain; the same list applies to additionalPaymentMeans[].typeCode. Code 30 additionally requires payeeFinancialAccountId (IBT-084, ibr-192-ae).", "type": "string" }, "payeeFinancialAccountId": { "type": "string" }, "seller": { "type": "object", "properties": { "name": { "type": "string" }, "endpoint": { "type": "object", "properties": { "scheme": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "scheme", "value" ] }, "legalRegistrationId": { "type": "string" }, "legalRegistrationIdType": { "type": "string" }, "taxRegistrationId": { "type": "string" }, "taxSchemeCode": { "type": "string" }, "identifier": { "description": "Party identifier — IBT-046 Buyer identifier on the buyer, IBT-029 Seller identifier on the seller; emitted as cac:PartyIdentification/cbc:ID without a scheme. On a 0235 buyer address other than a TIN (the predefined 0235:9900000097 / 0235:9900000098) without the export flag, the buyer needs taxRegistrationId OR identifier (ibr-135-ae), else 422 BUYER_IDENTIFIER_REQUIRED at buyer.identifier.", "type": "string" }, "address": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "city": { "type": "string" }, "postalZone": { "type": "string" }, "countrySubdivision": { "description": "Country subdivision (IBT-039/054/079). When countryCode is AE this must be the emirate code — AUH, DXB, SHJ, AJM, UAQ, RAK or FUJ (IBR-128-AE); a name such as \"Dubai\" or a retired code such as \"DU\" is rejected with 422 AE_EMIRATE_CODE naming the code to use. Free text for other countries.", "type": "string" }, "countryCode": { "type": "string" } }, "required": [ "addressLine1", "city", "countrySubdivision", "countryCode" ] }, "authorityName": { "type": "string" } }, "required": [ "name", "endpoint", "legalRegistrationId", "legalRegistrationIdType", "address" ] }, "buyer": { "type": "object", "properties": { "name": { "type": "string" }, "endpoint": { "type": "object", "properties": { "scheme": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "scheme", "value" ] }, "legalRegistrationId": { "type": "string" }, "legalRegistrationIdType": { "type": "string" }, "taxRegistrationId": { "type": "string" }, "taxSchemeCode": { "type": "string" }, "identifier": { "description": "Party identifier — IBT-046 Buyer identifier on the buyer, IBT-029 Seller identifier on the seller; emitted as cac:PartyIdentification/cbc:ID without a scheme. On a 0235 buyer address other than a TIN (the predefined 0235:9900000097 / 0235:9900000098) without the export flag, the buyer needs taxRegistrationId OR identifier (ibr-135-ae), else 422 BUYER_IDENTIFIER_REQUIRED at buyer.identifier.", "type": "string" }, "address": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "city": { "type": "string" }, "postalZone": { "type": "string" }, "countrySubdivision": { "description": "Country subdivision (IBT-039/054/079). When countryCode is AE this must be the emirate code — AUH, DXB, SHJ, AJM, UAQ, RAK or FUJ (IBR-128-AE); a name such as \"Dubai\" or a retired code such as \"DU\" is rejected with 422 AE_EMIRATE_CODE naming the code to use. Free text for other countries.", "type": "string" }, "countryCode": { "type": "string" } }, "required": [ "addressLine1", "city", "countrySubdivision", "countryCode" ] }, "authorityName": { "type": "string" } }, "required": [ "name", "endpoint", "legalRegistrationId", "legalRegistrationIdType", "address" ] }, "totals": { "type": "object", "properties": { "lineNetTotal": { "type": "string" }, "taxExclusiveAmount": { "type": "string" }, "taxTotalAmount": { "type": "string" }, "taxInclusiveAmount": { "type": "string" }, "allowanceTotalAmount": { "type": "string" }, "chargeTotalAmount": { "type": "string" }, "prepaidAmount": { "type": "string" }, "roundingAmount": { "type": "string" }, "amountDueForPayment": { "type": "string" }, "taxTotalAmountAed": { "type": "string" }, "taxInclusiveAmountAed": { "type": "string" } }, "required": [ "lineNetTotal", "taxExclusiveAmount", "taxTotalAmount", "taxInclusiveAmount", "amountDueForPayment" ] }, "taxBreakdown": { "type": "array", "items": { "type": "object", "properties": { "taxableAmount": { "type": "string" }, "taxAmount": { "type": "string" }, "categoryCode": { "type": "string" }, "rate": { "type": "string" }, "categoryExemptionReason": { "type": "string" }, "categoryExemptionReasonCode": { "type": "string" } }, "required": [ "taxableAmount", "taxAmount", "categoryCode", "rate" ] } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "string" }, "unitOfMeasureCode": { "type": "string" }, "netAmount": { "type": "string" }, "itemNetPrice": { "type": "string" }, "itemGrossPrice": { "type": "string" }, "itemPriceBaseQuantity": { "type": "string" }, "itemTaxCategoryCode": { "type": "string" }, "itemTaxRate": { "type": "string" }, "itemTaxExemptionReasonCode": { "description": "VAT exemption reason code (IBT-186), mandatory on an exempt (E) line. Closed list, one code per category of exempt supply in Article 46 of the VAT Decree-Law: DL8.46.1 certain financial services, DL8.46.2 supply of residential units (lease or sale), DL8.46.3 bare land, DL8.46.4 local passenger transport. Any other value is rejected with 422 INVALID_EXEMPTION_REASON_CODE naming the acceptable codes; the same list applies to taxBreakdown[].categoryExemptionReasonCode and to allowances[]/charges[].exemptionReasonCode. A free-text explanation belongs in itemTaxExemptionReason (IBT-185).", "type": "string" }, "itemTaxExemptionReason": { "type": "string" }, "vatLineAmountAed": { "type": "string" }, "lineAmountAed": { "type": "string" }, "itemName": { "type": "string" }, "itemDescription": { "type": "string" }, "standardItemIdentifier": { "type": "string" }, "commodityNatureCode": { "type": "string" }, "itemTypeCode": { "type": "string" }, "itemClassificationCode": { "type": "string" }, "serviceAccountingCode": { "type": "string" }, "batchNumber": { "type": "string" }, "allowances": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "reasonCode": { "type": "string" }, "reason": { "type": "string" }, "baseAmount": { "type": "string" }, "percentage": { "type": "string" } }, "required": [ "amount" ] } }, "charges": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "reasonCode": { "type": "string" }, "reason": { "type": "string" }, "baseAmount": { "type": "string" }, "percentage": { "type": "string" } }, "required": [ "amount" ] } } }, "required": [ "id", "quantity", "unitOfMeasureCode", "netAmount", "itemNetPrice", "itemGrossPrice", "itemPriceBaseQuantity", "itemTaxCategoryCode", "itemTaxRate", "itemName", "itemDescription" ] } }, "precedingInvoiceReferences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "issueDate": { "type": "string" } }, "required": [ "id" ] } }, "creditNoteReasonCode": { "description": "Adjustment ground: DL8.61.1.A cancellation; B nature/tax-treatment change; C consideration change; D return AND consideration repaid; E tax or treatment applied in error. VD is the separate volume discount code. VAT Law Art. 61(1), ADR-0238.", "type": "string" }, "adjustment": { "description": "AXS-internal credit-note correction event, YYYY-MM-DD; never sent to Peppol. Ground is creditNoteReasonCode. For DL8.61.1.D both return and repayment must have occurred. VAT Law Art. 62(2): 14 days excluding event day; a weekend or official Federal Government holiday endpoint moves to the next Business Day. Missing event is not assessable; lateness is advisory, never 422.", "type": "object", "properties": { "eventDate": { "type": "string" } }, "required": [ "eventDate" ] }, "beneficiary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ] }, "principal": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ] }, "invoicingPeriod": { "type": "object", "properties": { "startDate": { "type": "string" }, "endDate": { "type": "string" }, "frequencyCode": { "type": "string" } }, "required": [ "startDate", "endDate" ] }, "delivery": { "type": "object", "properties": { "address": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "city": { "type": "string" }, "postalZone": { "type": "string" }, "countrySubdivision": { "description": "Country subdivision (IBT-039/054/079). When countryCode is AE this must be the emirate code — AUH, DXB, SHJ, AJM, UAQ, RAK or FUJ (IBR-128-AE); a name such as \"Dubai\" or a retired code such as \"DU\" is rejected with 422 AE_EMIRATE_CODE naming the code to use. Free text for other countries.", "type": "string" }, "countryCode": { "type": "string" } }, "required": [ "addressLine1", "city", "countrySubdivision", "countryCode" ] }, "actualDeliveryDate": { "description": "Actual delivery date (IBT-072), YYYY-MM-DD, on any scenario. The address is only required on e-commerce/export (SCENARIO_DELIVERY_REQUIRED); a malformed date is 422 DELIVERY_DATE_FORMAT (ibr-073).", "type": "string" }, "deliverToPartyId": { "type": "string" }, "deliverToPartyName": { "type": "string" } } }, "allowances": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "reasonCode": { "type": "string" }, "reason": { "type": "string" }, "baseAmount": { "type": "string" }, "percentage": { "type": "string" }, "taxCategoryCode": { "type": "string" }, "taxRate": { "type": "string" }, "exemptionReasonCode": { "type": "string" }, "exemptionReason": { "type": "string" } }, "required": [ "amount", "taxCategoryCode" ] } }, "charges": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "reasonCode": { "type": "string" }, "reason": { "type": "string" }, "baseAmount": { "type": "string" }, "percentage": { "type": "string" }, "taxCategoryCode": { "type": "string" }, "taxRate": { "type": "string" }, "exemptionReasonCode": { "type": "string" }, "exemptionReason": { "type": "string" } }, "required": [ "amount", "taxCategoryCode" ] } }, "invoiceNote": { "type": "string" }, "incoterms": { "type": "string" }, "paymentTermsNote": { "type": "string" }, "additionalPaymentMeans": { "type": "array", "items": { "type": "object", "properties": { "typeCode": { "type": "string" }, "payeeFinancialAccountId": { "type": "string" } }, "required": [ "typeCode" ] } }, "buyerReference": { "description": "Buyer reference (IBT-010, cbc:BuyerReference): the buyer's own identifier (e.g. cost centre) to be quoted back. Free text; must not be blank when present (422 DOCUMENT_REFERENCE_BLANK).", "type": "string" }, "orderReference": { "description": "Purchase order reference (IBT-013, cac:OrderReference/cbc:ID): the buyer's order number. Free text; must not be blank when present.", "type": "string" }, "contractReference": { "description": "Contract reference (IBT-012, cac:ContractDocumentReference/cbc:ID). Free text, at most one (ibr-094); must not be blank when present.", "type": "string" }, "attachments": { "description": "Additional supporting documents (IBG-24): each one has an id and an embedded file (base64 + mimeCode + filename) and/or an external URI. Allowed MIME codes: application/pdf, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/xml, application/vnd.oasis.opendocument.spreadsheet — the pack's ibr-cl-24 list (application/pdf, image/png, image/jpeg, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/xml, application/vnd.oasis.opendocument.spreadsheet) minus image/png and image/jpeg: the UAE rules allow no QR code or barcode on the electronic invoice ([G] 5.3), and an image could carry one, so an image attachment is 422 ATTACHMENT_IMAGE_REFUSED at attachments[i].embedded.mimeCode. At most 10 documents, their decoded files totalling at most 512 KiB (the base64 body must also fit the 1 MiB request limit). Every embedded file is malware-scanned before admission: an infected file is 422 ATTACHMENT_MALWARE and quarantined, a scan that cannot run is 503. A refused type or size is 422 ATTACHMENT_MIME / ATTACHMENT_SIZE at the field.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Supporting document reference (IBT-122); not blank (ibr-052).", "type": "string" }, "description": { "description": "Supporting document description (IBT-123).", "type": "string" }, "externalUri": { "description": "External document location (IBT-124): an absolute http(s) URI, at most 2048 characters.", "type": "string" }, "embedded": { "description": "Attached document (IBT-125), embedded as base64.", "type": "object", "properties": { "content": { "description": "The file content, base64 (RFC 4648).", "type": "string" }, "mimeCode": { "description": "MIME code (IBT-125-1): one of application/pdf, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/xml, application/vnd.oasis.opendocument.spreadsheet — the ibr-cl-24 list without its two image types, which an issued invoice may not carry ([G] 5.3).", "type": "string" }, "filename": { "description": "File name (IBT-125-2), required (ibr-075).", "type": "string" } }, "required": [ "content", "mimeCode", "filename" ] } }, "required": [ "id" ] } }, "paymentReceiptDate": { "description": "Date payment for the business transaction was received, YYYY-MM-DD. AXS-internal: never emitted to the Peppol network. Read only by the advisory issuing-deadline assessment, which counts the 14 days from the EARLIEST of the date of supply, the actual delivery date and this date (MD 243/2025 Art. 1 and 6(5)). A malformed date is 422 PAYMENT_RECEIPT_DATE_FORMAT.", "type": "string" } }, "required": [ "id", "uuid", "issueDate", "documentKind", "billingMode", "typeCode", "currencyCode", "transactionTypeCode", "paymentDueDate", "businessProcessType", "specificationIdentifier", "paymentMeansTypeCode", "seller", "buyer", "totals", "taxBreakdown", "lines" ] }, "numberSeries": { "type": "object", "properties": { "seriesId": { "description": "Portal-only (human issuer). The tenant number series the invoice.id was suggested from; the number is verified and consumed at issuance. Integrations number their own invoices and must omit this field.", "type": "string", "format": "uuid" } }, "required": [ "seriesId" ] } }, "required": [ "sbdh", "invoice" ] }, "IngestResultDto": { "type": "object", "properties": { "integrationId": { "type": "string" }, "outcome": { "type": "string" }, "created": { "type": "boolean" }, "routeClass": { "type": "string", "nullable": true }, "rulePackId": { "type": "string", "nullable": true }, "warnings": { "description": "Advisory findings that did NOT affect the outcome: the document was accepted. Five codes today from four producers, always in this order. Two are about the 14-day issuing window (MD 243/2025 Art. 6(5)): ISSUE_DEADLINE_EXCEEDED — the document was issued after the window: event day excluded, 14 calendar days later, with an endpoint on Saturday, Sunday or an official Federal Government holiday extended to the next Business Day (TPL Art. 1, 49; FAHR-sourced holiday list, ADR-0254). The basis is the earliest entitled supply, delivery, payment receipt or periodic-supply end date; a summary invoice uses the end of that calendar month (VAT ER 59(13)(b)). With no separate basis the issue date is used (VAT ER 59(1)(f)). Credit notes use ONLY the declared adjustment.eventDate (ADR-0238), never a supply, payment or issue-date fallback, as an AXS advisory window: VAT Law Art. 62(2) governs applicable tax corrections, and AXS does not determine the event. Commercial and VD documents get the same calculation without an automatic legal-duty claim. The message names the document kind (invoice or credit note). ISSUE_DEADLINE_NOT_ASSESSABLE means an explicitly malformed basis date or a missing credit-note adjustment event. The holiday list is incomplete for 2026, which can only make the window shorter. The third is about the taxable basis: PREPAID_TAXABLE_BASIS — the invoice deducts a prepaid amount (IBT-113), which lowers the amount due only: its taxable amount and VAT must cover only what has not been taxed on an earlier tax invoice (UAE E-Invoicing Guidelines V1.1 §17.1). The fourth, one per line, is about a summary invoice: SUMMARY_NETTED_RETURN — a line of a summary invoice has a negative net amount (IBT-131); a return or other downward adjustment belongs on a credit note, not netted against unrelated supply lines; its path is that line (`lines[i].netAmount`). The fifth is about the same document: SUMMARY_PERIOD_SPANS_MONTHS — the stated supply-side dates of a summary invoice (period start and end, date of supply, actual delivery date, payment receipt date) fall in more than one calendar month; VAT ER Art. 59(6) and 59(13)(b) allow one summary tax invoice only for the supplies of one calendar month, so supplies of another month belong on a separate summary invoice. Its path is `invoicingPeriod.endDate`; the issuing-deadline basis is unchanged. Line-level dates are not modelled. Empty when there is nothing to say.", "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "path": { "description": "Dotted canonical path, same form as a `violations[].path` (ADR-0145).", "type": "string" }, "message": { "type": "string" } }, "required": [ "rule", "path", "message" ] } } }, "required": [ "integrationId", "outcome", "created", "routeClass", "rulePackId", "warnings" ] }, "ConflictResultDto": { "type": "object", "properties": { "error": { "type": "string" }, "integrationId": { "type": "string" } }, "required": [ "error", "integrationId" ] }, "ViolationsDto": { "type": "object", "properties": { "violations": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "path": { "description": "Dotted canonical path rooted at the invoice, with no `invoice.` prefix (`seller.name`, `uuid`, `lines[0].itemName`); non-invoice envelope parts keep their own root (`sbdh.sender`). Empty when the finding names no field. PINT-AE rule-pack findings carry the Schematron location's XPath instead.", "type": "string" }, "message": { "type": "string" }, "detail": { "description": "Only on SELLER_NOT_REGISTERED when the tenant owns other participants: the issuing participant that was checked and the tenant's registered participants (`scheme:value`).", "type": "object", "properties": { "issuerParticipantId": { "type": "string" }, "registeredParticipantIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "issuerParticipantId", "registeredParticipantIds" ] } }, "required": [ "rule", "path", "message" ] } } }, "required": [ "violations" ] }, "DocumentViewDto": { "type": "object", "properties": { "integrationId": { "type": "string" }, "legs": { "type": "array", "items": { "type": "object", "properties": { "leg": { "type": "string" }, "state": { "type": "string" }, "rank": { "type": "number" }, "reopenEpoch": { "type": "number" }, "appliedReopenIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "leg", "state", "rank", "reopenEpoch", "appliedReopenIds" ] } }, "routeClass": { "type": "string", "nullable": true }, "rulePackId": { "type": "string", "nullable": true }, "direction": { "type": "string" }, "invalidatedBy": { "description": "Derived workflow links to admitted credit notes with one explicit reference, matching parties and currency, and the full positive gross amount. VD means Volume Discount and never bypasses the amount check. Not transport/FTA acceptance; no leg state changes. Empty for ambiguity or more than 100 candidates.", "type": "array", "items": { "type": "object", "properties": { "integrationId": { "type": "string" }, "invoiceId": { "type": "string" }, "basis": { "type": "string", "enum": [ "full-credit" ] }, "direction": { "description": "Which detail view shows the credit note to this tenant (same evidence rule as the top-level `direction`).", "type": "string", "enum": [ "inbound", "outbound" ] } }, "required": [ "integrationId", "invoiceId", "basis", "direction" ] } }, "header": { "type": "object", "properties": { "id": { "type": "string" }, "uuid": { "type": "string" }, "issueDate": { "type": "string" }, "taxPointDate": { "type": "string" }, "documentKind": { "type": "string" }, "typeCode": { "type": "string" }, "billingMode": { "type": "string" }, "currencyCode": { "type": "string" }, "seller": { "type": "object", "properties": { "name": { "type": "string" }, "trn": { "type": "string", "nullable": true } }, "required": [ "name", "trn" ] }, "buyer": { "type": "object", "properties": { "name": { "type": "string" }, "trn": { "type": "string", "nullable": true } }, "required": [ "name", "trn" ] }, "totals": { "type": "object", "properties": { "taxExclusiveAmount": { "type": "string" }, "taxTotalAmount": { "type": "string" }, "taxInclusiveAmount": { "type": "string" }, "amountDueForPayment": { "type": "string" } }, "required": [ "taxExclusiveAmount", "taxTotalAmount", "taxInclusiveAmount", "amountDueForPayment" ] } }, "required": [ "id", "uuid", "issueDate", "documentKind", "typeCode", "billingMode", "currencyCode", "seller", "buyer", "totals" ], "nullable": true }, "dispatch": { "type": "object", "properties": { "outbound": { "type": "object", "properties": { "status": { "type": "string" }, "attempts": { "type": "number" }, "deadlineMs": { "type": "number" }, "backendTxId": { "type": "string", "nullable": true }, "archiveReceipt": { "type": "string", "nullable": true } }, "required": [ "status", "attempts", "deadlineMs", "backendTxId", "archiveReceipt" ], "nullable": true }, "reporting": { "type": "array", "items": { "type": "object", "properties": { "corner": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "number" }, "backendTxId": { "type": "string", "nullable": true }, "cdpReference": { "type": "string", "nullable": true }, "archiveReceipt": { "type": "string", "nullable": true }, "failureReason": { "type": "string", "nullable": true } }, "required": [ "corner", "status", "attempts", "backendTxId", "cdpReference", "archiveReceipt", "failureReason" ] } }, "inbound": { "type": "object", "properties": { "status": { "type": "string" }, "attempts": { "type": "number" }, "archiveReceipt": { "type": "string", "nullable": true } }, "required": [ "status", "attempts", "archiveReceipt" ], "nullable": true } }, "required": [ "outbound", "reporting", "inbound" ] }, "artifact": { "type": "object", "properties": { "stored": { "type": "boolean" }, "envelopeStored": { "description": "True when the stored wire copy also holds the full SBDH envelope (sbdhXml on /documents/{id}/ubl with source \"stored\"): outbound once signed, inbound when received after AXS-316. False for a re-rendered copy or an older receipt.", "type": "boolean" } }, "required": [ "stored", "envelopeStored" ] }, "envelopes": { "description": "Per-leg Peppol envelope (SBDH) sender/receiver, read from the STORED envelope — never recomputed from the UBL. `sender`/`receiver` are null when no envelope is stored for that leg (not yet signed/sent, or an inbound TRANSPORT leg received before the received envelope was kept — AXS-316).", "type": "array", "items": { "type": "object", "properties": { "leg": { "type": "string", "enum": [ "TRANSPORT", "C5_C2", "C5_C3", "C4_DELIVERY", "INBOUND_MLS_OUT" ] }, "sender": { "type": "object", "properties": { "identifier": { "type": "string" }, "authority": { "type": "string", "nullable": true } }, "required": [ "identifier", "authority" ], "nullable": true }, "receiver": { "type": "object", "properties": { "identifier": { "type": "string" }, "authority": { "type": "string", "nullable": true } }, "required": [ "identifier", "authority" ], "nullable": true }, "senderName": { "description": "Resolved name of the envelope sender for the caller's tenant: the company's own name for one of its registered participants, or a partner whose endpoint matches exactly one partner record. Null when unknown or ambiguous — show the identifier.", "type": "string", "nullable": true }, "receiverName": { "description": "Resolved name of the envelope receiver — same rule as `senderName`.", "type": "string", "nullable": true } }, "required": [ "leg", "sender", "receiver", "senderName", "receiverName" ] } } }, "required": [ "integrationId", "legs", "routeClass", "rulePackId", "direction", "header", "dispatch", "artifact", "envelopes" ] }, "IngestFileResultDto": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "duplicate": { "type": "integer" }, "conflict": { "type": "integer" }, "invalid": { "type": "integer" } }, "required": [ "total", "created", "duplicate", "conflict", "invalid" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "index": { "description": "Zero-based position of the invoice in the file.", "type": "integer" }, "sourceRef": { "description": "Where the invoice came from: `ubl`, or `csv-rows` with the physical row range.", "type": "object", "properties": { "kind": { "type": "string" }, "from": { "type": "number" }, "to": { "type": "number" } }, "required": [ "kind" ] }, "invoiceId": { "type": "string" }, "kind": { "description": "The ingest decision for THIS invoice — the same words as an async job `result.kind`. `created` = admitted now (like a sync 201), `duplicate` = identical content already admitted (200), `conflict` = same tenant + invoice ID with different content (409), `invalid` = rejected (422), nothing stored.", "type": "string", "enum": [ "created", "duplicate", "conflict", "invalid" ] }, "integrationId": { "type": "string" }, "outcome": { "description": "Current document outcome (created/duplicate only).", "type": "string" }, "routeClass": { "type": "string", "nullable": true }, "rulePackId": { "type": "string", "nullable": true }, "violations": { "description": "Why an `invalid` invoice was rejected — the same list the sync 422 carries.", "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "path": { "type": "string" }, "message": { "type": "string" }, "csv": { "type": "object", "properties": { "code": { "type": "string" }, "column": { "type": "string" }, "from": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "to": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "required": [ "code" ] }, "detail": { "description": "Only on SELLER_NOT_REGISTERED when the tenant owns other participants: the issuing participant that was checked and the tenant's registered participants (`scheme:value`).", "type": "object", "properties": { "issuerParticipantId": { "type": "string" }, "registeredParticipantIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "issuerParticipantId", "registeredParticipantIds" ] } }, "required": [ "rule", "path", "message" ] } }, "warnings": { "description": "Advisory findings that did NOT affect the outcome: the document was accepted. Five codes today from four producers, always in this order. Two are about the 14-day issuing window (MD 243/2025 Art. 6(5)): ISSUE_DEADLINE_EXCEEDED — the document was issued after the window: event day excluded, 14 calendar days later, with an endpoint on Saturday, Sunday or an official Federal Government holiday extended to the next Business Day (TPL Art. 1, 49; FAHR-sourced holiday list, ADR-0254). The basis is the earliest entitled supply, delivery, payment receipt or periodic-supply end date; a summary invoice uses the end of that calendar month (VAT ER 59(13)(b)). With no separate basis the issue date is used (VAT ER 59(1)(f)). Credit notes use ONLY the declared adjustment.eventDate (ADR-0238), never a supply, payment or issue-date fallback, as an AXS advisory window: VAT Law Art. 62(2) governs applicable tax corrections, and AXS does not determine the event. Commercial and VD documents get the same calculation without an automatic legal-duty claim. The message names the document kind (invoice or credit note). ISSUE_DEADLINE_NOT_ASSESSABLE means an explicitly malformed basis date or a missing credit-note adjustment event. The holiday list is incomplete for 2026, which can only make the window shorter. The third is about the taxable basis: PREPAID_TAXABLE_BASIS — the invoice deducts a prepaid amount (IBT-113), which lowers the amount due only: its taxable amount and VAT must cover only what has not been taxed on an earlier tax invoice (UAE E-Invoicing Guidelines V1.1 §17.1). The fourth, one per line, is about a summary invoice: SUMMARY_NETTED_RETURN — a line of a summary invoice has a negative net amount (IBT-131); a return or other downward adjustment belongs on a credit note, not netted against unrelated supply lines; its path is that line (`lines[i].netAmount`). The fifth is about the same document: SUMMARY_PERIOD_SPANS_MONTHS — the stated supply-side dates of a summary invoice (period start and end, date of supply, actual delivery date, payment receipt date) fall in more than one calendar month; VAT ER Art. 59(6) and 59(13)(b) allow one summary tax invoice only for the supplies of one calendar month, so supplies of another month belong on a separate summary invoice. Its path is `invoicingPeriod.endDate`; the issuing-deadline basis is unchanged. Line-level dates are not modelled. Empty when there is nothing to say.", "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "path": { "description": "Dotted canonical path, same form as a `violations[].path` (ADR-0145).", "type": "string" }, "message": { "type": "string" } }, "required": [ "rule", "path", "message" ] } }, "report": { "description": "The PINT-AE validation report (UBL XSD + both Schematron layers) of this submission, including warnings on an ACCEPTED invoice. Absent when the invoice was rejected before the rule pack ran (envelope, structure, registration, CSV row errors).", "type": "object", "properties": { "rulePackId": { "type": "string" }, "valid": { "type": "boolean" }, "layers": { "type": "array", "items": { "type": "object", "properties": { "layer": { "type": "string" }, "status": { "type": "string" } }, "required": [ "layer", "status" ] } }, "findings": { "type": "array", "items": { "type": "object", "properties": { "layer": { "type": "string" }, "severity": { "type": "string" }, "ruleId": { "type": "string" }, "location": { "type": "string" }, "test": { "type": "string" }, "message": { "type": "string" } }, "required": [ "layer", "severity", "location", "message" ] } } }, "required": [ "rulePackId", "valid", "layers", "findings" ] } }, "required": [ "index", "sourceRef", "kind", "violations", "warnings" ] } } }, "required": [ "summary", "items" ] }, "FileViolationsDto": { "type": "object", "properties": { "violations": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "path": { "type": "string" }, "message": { "type": "string" }, "csv": { "type": "object", "properties": { "code": { "type": "string" }, "column": { "type": "string" }, "from": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "to": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "required": [ "code" ] }, "detail": { "description": "Only on SELLER_NOT_REGISTERED when the tenant owns other participants: the issuing participant that was checked and the tenant's registered participants (`scheme:value`).", "type": "object", "properties": { "issuerParticipantId": { "type": "string" }, "registeredParticipantIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "issuerParticipantId", "registeredParticipantIds" ] } }, "required": [ "rule", "path", "message" ] } } }, "required": [ "violations" ] }, "InvoiceDto": { "type": "object", "properties": { "id": { "type": "string" }, "uuid": { "type": "string" }, "issueDate": { "type": "string" }, "documentKind": { "type": "string" }, "billingMode": { "type": "string" }, "typeCode": { "type": "string" }, "currencyCode": { "type": "string" }, "exchangeRate": { "type": "string" }, "transactionTypeCode": { "type": "string" }, "paymentDueDate": { "type": "string" }, "taxPointDate": { "type": "string" }, "businessProcessType": { "type": "string" }, "specificationIdentifier": { "type": "string" }, "paymentMeansTypeCode": { "description": "Payment means type code (IBT-081), mandatory. Closed list — PINT AE publishes its own UNCL4461 subset, \"Payment means codes used in AE\": 1 instrument not defined, 10 in cash, 20 cheque, 21 banker's draft, 30 credit transfer, 49 direct debit, 54 credit card, 55 debit card, 68 online payment service. Any other value is rejected with 422 INVALID_PAYMENT_MEANS_CODE naming the acceptable codes, including UNCL4461 codes such as 48 that the Schematron would take but the AE list does not contain; the same list applies to additionalPaymentMeans[].typeCode. Code 30 additionally requires payeeFinancialAccountId (IBT-084, ibr-192-ae).", "type": "string" }, "payeeFinancialAccountId": { "type": "string" }, "seller": { "type": "object", "properties": { "name": { "type": "string" }, "endpoint": { "type": "object", "properties": { "scheme": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "scheme", "value" ] }, "legalRegistrationId": { "type": "string" }, "legalRegistrationIdType": { "type": "string" }, "taxRegistrationId": { "type": "string" }, "taxSchemeCode": { "type": "string" }, "identifier": { "description": "Party identifier — IBT-046 Buyer identifier on the buyer, IBT-029 Seller identifier on the seller; emitted as cac:PartyIdentification/cbc:ID without a scheme. On a 0235 buyer address other than a TIN (the predefined 0235:9900000097 / 0235:9900000098) without the export flag, the buyer needs taxRegistrationId OR identifier (ibr-135-ae), else 422 BUYER_IDENTIFIER_REQUIRED at buyer.identifier.", "type": "string" }, "address": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "city": { "type": "string" }, "postalZone": { "type": "string" }, "countrySubdivision": { "description": "Country subdivision (IBT-039/054/079). When countryCode is AE this must be the emirate code — AUH, DXB, SHJ, AJM, UAQ, RAK or FUJ (IBR-128-AE); a name such as \"Dubai\" or a retired code such as \"DU\" is rejected with 422 AE_EMIRATE_CODE naming the code to use. Free text for other countries.", "type": "string" }, "countryCode": { "type": "string" } }, "required": [ "addressLine1", "city", "countrySubdivision", "countryCode" ] }, "authorityName": { "type": "string" } }, "required": [ "name", "endpoint", "legalRegistrationId", "legalRegistrationIdType", "address" ] }, "buyer": { "type": "object", "properties": { "name": { "type": "string" }, "endpoint": { "type": "object", "properties": { "scheme": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "scheme", "value" ] }, "legalRegistrationId": { "type": "string" }, "legalRegistrationIdType": { "type": "string" }, "taxRegistrationId": { "type": "string" }, "taxSchemeCode": { "type": "string" }, "identifier": { "description": "Party identifier — IBT-046 Buyer identifier on the buyer, IBT-029 Seller identifier on the seller; emitted as cac:PartyIdentification/cbc:ID without a scheme. On a 0235 buyer address other than a TIN (the predefined 0235:9900000097 / 0235:9900000098) without the export flag, the buyer needs taxRegistrationId OR identifier (ibr-135-ae), else 422 BUYER_IDENTIFIER_REQUIRED at buyer.identifier.", "type": "string" }, "address": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "city": { "type": "string" }, "postalZone": { "type": "string" }, "countrySubdivision": { "description": "Country subdivision (IBT-039/054/079). When countryCode is AE this must be the emirate code — AUH, DXB, SHJ, AJM, UAQ, RAK or FUJ (IBR-128-AE); a name such as \"Dubai\" or a retired code such as \"DU\" is rejected with 422 AE_EMIRATE_CODE naming the code to use. Free text for other countries.", "type": "string" }, "countryCode": { "type": "string" } }, "required": [ "addressLine1", "city", "countrySubdivision", "countryCode" ] }, "authorityName": { "type": "string" } }, "required": [ "name", "endpoint", "legalRegistrationId", "legalRegistrationIdType", "address" ] }, "totals": { "type": "object", "properties": { "lineNetTotal": { "type": "string" }, "taxExclusiveAmount": { "type": "string" }, "taxTotalAmount": { "type": "string" }, "taxInclusiveAmount": { "type": "string" }, "allowanceTotalAmount": { "type": "string" }, "chargeTotalAmount": { "type": "string" }, "prepaidAmount": { "type": "string" }, "roundingAmount": { "type": "string" }, "amountDueForPayment": { "type": "string" }, "taxTotalAmountAed": { "type": "string" }, "taxInclusiveAmountAed": { "type": "string" } }, "required": [ "lineNetTotal", "taxExclusiveAmount", "taxTotalAmount", "taxInclusiveAmount", "amountDueForPayment" ] }, "taxBreakdown": { "type": "array", "items": { "type": "object", "properties": { "taxableAmount": { "type": "string" }, "taxAmount": { "type": "string" }, "categoryCode": { "type": "string" }, "rate": { "type": "string" }, "categoryExemptionReason": { "type": "string" }, "categoryExemptionReasonCode": { "type": "string" } }, "required": [ "taxableAmount", "taxAmount", "categoryCode", "rate" ] } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "string" }, "unitOfMeasureCode": { "type": "string" }, "netAmount": { "type": "string" }, "itemNetPrice": { "type": "string" }, "itemGrossPrice": { "type": "string" }, "itemPriceBaseQuantity": { "type": "string" }, "itemTaxCategoryCode": { "type": "string" }, "itemTaxRate": { "type": "string" }, "itemTaxExemptionReasonCode": { "description": "VAT exemption reason code (IBT-186), mandatory on an exempt (E) line. Closed list, one code per category of exempt supply in Article 46 of the VAT Decree-Law: DL8.46.1 certain financial services, DL8.46.2 supply of residential units (lease or sale), DL8.46.3 bare land, DL8.46.4 local passenger transport. Any other value is rejected with 422 INVALID_EXEMPTION_REASON_CODE naming the acceptable codes; the same list applies to taxBreakdown[].categoryExemptionReasonCode and to allowances[]/charges[].exemptionReasonCode. A free-text explanation belongs in itemTaxExemptionReason (IBT-185).", "type": "string" }, "itemTaxExemptionReason": { "type": "string" }, "vatLineAmountAed": { "type": "string" }, "lineAmountAed": { "type": "string" }, "itemName": { "type": "string" }, "itemDescription": { "type": "string" }, "standardItemIdentifier": { "type": "string" }, "commodityNatureCode": { "type": "string" }, "itemTypeCode": { "type": "string" }, "itemClassificationCode": { "type": "string" }, "serviceAccountingCode": { "type": "string" }, "batchNumber": { "type": "string" }, "allowances": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "reasonCode": { "type": "string" }, "reason": { "type": "string" }, "baseAmount": { "type": "string" }, "percentage": { "type": "string" } }, "required": [ "amount" ] } }, "charges": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "reasonCode": { "type": "string" }, "reason": { "type": "string" }, "baseAmount": { "type": "string" }, "percentage": { "type": "string" } }, "required": [ "amount" ] } } }, "required": [ "id", "quantity", "unitOfMeasureCode", "netAmount", "itemNetPrice", "itemGrossPrice", "itemPriceBaseQuantity", "itemTaxCategoryCode", "itemTaxRate", "itemName", "itemDescription" ] } }, "precedingInvoiceReferences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "issueDate": { "type": "string" } }, "required": [ "id" ] } }, "creditNoteReasonCode": { "description": "Adjustment ground: DL8.61.1.A cancellation; B nature/tax-treatment change; C consideration change; D return AND consideration repaid; E tax or treatment applied in error. VD is the separate volume discount code. VAT Law Art. 61(1), ADR-0238.", "type": "string" }, "adjustment": { "description": "AXS-internal credit-note correction event, YYYY-MM-DD; never sent to Peppol. Ground is creditNoteReasonCode. For DL8.61.1.D both return and repayment must have occurred. VAT Law Art. 62(2): 14 days excluding event day; a weekend or official Federal Government holiday endpoint moves to the next Business Day. Missing event is not assessable; lateness is advisory, never 422.", "type": "object", "properties": { "eventDate": { "type": "string" } }, "required": [ "eventDate" ] }, "beneficiary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ] }, "principal": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ] }, "invoicingPeriod": { "type": "object", "properties": { "startDate": { "type": "string" }, "endDate": { "type": "string" }, "frequencyCode": { "type": "string" } }, "required": [ "startDate", "endDate" ] }, "delivery": { "type": "object", "properties": { "address": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "city": { "type": "string" }, "postalZone": { "type": "string" }, "countrySubdivision": { "description": "Country subdivision (IBT-039/054/079). When countryCode is AE this must be the emirate code — AUH, DXB, SHJ, AJM, UAQ, RAK or FUJ (IBR-128-AE); a name such as \"Dubai\" or a retired code such as \"DU\" is rejected with 422 AE_EMIRATE_CODE naming the code to use. Free text for other countries.", "type": "string" }, "countryCode": { "type": "string" } }, "required": [ "addressLine1", "city", "countrySubdivision", "countryCode" ] }, "actualDeliveryDate": { "description": "Actual delivery date (IBT-072), YYYY-MM-DD, on any scenario. The address is only required on e-commerce/export (SCENARIO_DELIVERY_REQUIRED); a malformed date is 422 DELIVERY_DATE_FORMAT (ibr-073).", "type": "string" }, "deliverToPartyId": { "type": "string" }, "deliverToPartyName": { "type": "string" } } }, "allowances": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "reasonCode": { "type": "string" }, "reason": { "type": "string" }, "baseAmount": { "type": "string" }, "percentage": { "type": "string" }, "taxCategoryCode": { "type": "string" }, "taxRate": { "type": "string" }, "exemptionReasonCode": { "type": "string" }, "exemptionReason": { "type": "string" } }, "required": [ "amount", "taxCategoryCode" ] } }, "charges": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "reasonCode": { "type": "string" }, "reason": { "type": "string" }, "baseAmount": { "type": "string" }, "percentage": { "type": "string" }, "taxCategoryCode": { "type": "string" }, "taxRate": { "type": "string" }, "exemptionReasonCode": { "type": "string" }, "exemptionReason": { "type": "string" } }, "required": [ "amount", "taxCategoryCode" ] } }, "invoiceNote": { "type": "string" }, "incoterms": { "type": "string" }, "paymentTermsNote": { "type": "string" }, "additionalPaymentMeans": { "type": "array", "items": { "type": "object", "properties": { "typeCode": { "type": "string" }, "payeeFinancialAccountId": { "type": "string" } }, "required": [ "typeCode" ] } }, "buyerReference": { "description": "Buyer reference (IBT-010, cbc:BuyerReference): the buyer's own identifier (e.g. cost centre) to be quoted back. Free text; must not be blank when present (422 DOCUMENT_REFERENCE_BLANK).", "type": "string" }, "orderReference": { "description": "Purchase order reference (IBT-013, cac:OrderReference/cbc:ID): the buyer's order number. Free text; must not be blank when present.", "type": "string" }, "contractReference": { "description": "Contract reference (IBT-012, cac:ContractDocumentReference/cbc:ID). Free text, at most one (ibr-094); must not be blank when present.", "type": "string" }, "attachments": { "description": "Additional supporting documents (IBG-24): each one has an id and an embedded file (base64 + mimeCode + filename) and/or an external URI. Allowed MIME codes: application/pdf, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/xml, application/vnd.oasis.opendocument.spreadsheet — the pack's ibr-cl-24 list (application/pdf, image/png, image/jpeg, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/xml, application/vnd.oasis.opendocument.spreadsheet) minus image/png and image/jpeg: the UAE rules allow no QR code or barcode on the electronic invoice ([G] 5.3), and an image could carry one, so an image attachment is 422 ATTACHMENT_IMAGE_REFUSED at attachments[i].embedded.mimeCode. At most 10 documents, their decoded files totalling at most 512 KiB (the base64 body must also fit the 1 MiB request limit). Every embedded file is malware-scanned before admission: an infected file is 422 ATTACHMENT_MALWARE and quarantined, a scan that cannot run is 503. A refused type or size is 422 ATTACHMENT_MIME / ATTACHMENT_SIZE at the field.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Supporting document reference (IBT-122); not blank (ibr-052).", "type": "string" }, "description": { "description": "Supporting document description (IBT-123).", "type": "string" }, "externalUri": { "description": "External document location (IBT-124): an absolute http(s) URI, at most 2048 characters.", "type": "string" }, "embedded": { "description": "Attached document (IBT-125), embedded as base64.", "type": "object", "properties": { "content": { "description": "The file content, base64 (RFC 4648).", "type": "string" }, "mimeCode": { "description": "MIME code (IBT-125-1): one of application/pdf, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/xml, application/vnd.oasis.opendocument.spreadsheet — the ibr-cl-24 list without its two image types, which an issued invoice may not carry ([G] 5.3).", "type": "string" }, "filename": { "description": "File name (IBT-125-2), required (ibr-075).", "type": "string" } }, "required": [ "content", "mimeCode", "filename" ] } }, "required": [ "id" ] } }, "paymentReceiptDate": { "description": "Date payment for the business transaction was received, YYYY-MM-DD. AXS-internal: never emitted to the Peppol network. Read only by the advisory issuing-deadline assessment, which counts the 14 days from the EARLIEST of the date of supply, the actual delivery date and this date (MD 243/2025 Art. 1 and 6(5)). A malformed date is 422 PAYMENT_RECEIPT_DATE_FORMAT.", "type": "string" } }, "required": [ "id", "uuid", "issueDate", "documentKind", "billingMode", "typeCode", "currencyCode", "transactionTypeCode", "paymentDueDate", "businessProcessType", "specificationIdentifier", "paymentMeansTypeCode", "seller", "buyer", "totals", "taxBreakdown", "lines" ] }, "InvoiceUblResultDto": { "type": "object", "properties": { "report": { "type": "object", "properties": { "rulePackId": { "type": "string" }, "valid": { "type": "boolean" }, "layers": { "type": "array", "items": { "type": "object", "properties": { "layer": { "type": "string" }, "status": { "type": "string" } }, "required": [ "layer", "status" ] } }, "findings": { "type": "array", "items": { "type": "object", "properties": { "layer": { "type": "string" }, "severity": { "type": "string" }, "ruleId": { "type": "string" }, "location": { "type": "string" }, "test": { "type": "string" }, "message": { "type": "string" } }, "required": [ "layer", "severity", "location", "message" ] } } }, "required": [ "rulePackId", "valid", "layers", "findings" ] }, "ubl": { "type": "string" }, "sbdh": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "scheme": { "type": "string" }, "value": { "type": "string" } }, "required": [ "scheme", "value" ] }, "receiver": { "type": "object", "properties": { "scheme": { "type": "string" }, "value": { "type": "string" } }, "required": [ "scheme", "value" ] } }, "required": [ "sender", "receiver" ] }, "warnings": { "description": "Advisory findings that did NOT affect the outcome: the document was accepted. Five codes today from four producers, always in this order. Two are about the 14-day issuing window (MD 243/2025 Art. 6(5)): ISSUE_DEADLINE_EXCEEDED — the document was issued after the window: event day excluded, 14 calendar days later, with an endpoint on Saturday, Sunday or an official Federal Government holiday extended to the next Business Day (TPL Art. 1, 49; FAHR-sourced holiday list, ADR-0254). The basis is the earliest entitled supply, delivery, payment receipt or periodic-supply end date; a summary invoice uses the end of that calendar month (VAT ER 59(13)(b)). With no separate basis the issue date is used (VAT ER 59(1)(f)). Credit notes use ONLY the declared adjustment.eventDate (ADR-0238), never a supply, payment or issue-date fallback, as an AXS advisory window: VAT Law Art. 62(2) governs applicable tax corrections, and AXS does not determine the event. Commercial and VD documents get the same calculation without an automatic legal-duty claim. The message names the document kind (invoice or credit note). ISSUE_DEADLINE_NOT_ASSESSABLE means an explicitly malformed basis date or a missing credit-note adjustment event. The holiday list is incomplete for 2026, which can only make the window shorter. The third is about the taxable basis: PREPAID_TAXABLE_BASIS — the invoice deducts a prepaid amount (IBT-113), which lowers the amount due only: its taxable amount and VAT must cover only what has not been taxed on an earlier tax invoice (UAE E-Invoicing Guidelines V1.1 §17.1). The fourth, one per line, is about a summary invoice: SUMMARY_NETTED_RETURN — a line of a summary invoice has a negative net amount (IBT-131); a return or other downward adjustment belongs on a credit note, not netted against unrelated supply lines; its path is that line (`lines[i].netAmount`). The fifth is about the same document: SUMMARY_PERIOD_SPANS_MONTHS — the stated supply-side dates of a summary invoice (period start and end, date of supply, actual delivery date, payment receipt date) fall in more than one calendar month; VAT ER Art. 59(6) and 59(13)(b) allow one summary tax invoice only for the supplies of one calendar month, so supplies of another month belong on a separate summary invoice. Its path is `invoicingPeriod.endDate`; the issuing-deadline basis is unchanged. Line-level dates are not modelled. Empty when there is nothing to say.", "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "path": { "description": "Dotted canonical path, same form as a `violations[].path` (ADR-0145).", "type": "string" }, "message": { "type": "string" } }, "required": [ "rule", "path", "message" ] } } }, "required": [ "report", "ubl", "sbdh", "warnings" ] }, "FileValidationResultDto": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "total": { "type": "number" }, "valid": { "type": "number" }, "invalid": { "type": "number" } }, "required": [ "total", "valid", "invalid" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "sourceRef": { "type": "object", "properties": { "kind": { "type": "string" }, "from": { "type": "number" }, "to": { "type": "number" } }, "required": [ "kind" ] }, "status": { "type": "string", "enum": [ "valid", "invalid" ] }, "violations": { "type": "array", "items": { "type": "object", "properties": { "rule": { "type": "string" }, "path": { "type": "string" }, "message": { "type": "string" }, "csv": { "type": "object", "properties": { "code": { "type": "string" }, "column": { "type": "string" }, "from": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "to": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "required": [ "code" ] }, "detail": { "description": "Only on SELLER_NOT_REGISTERED when the tenant owns other participants: the issuing participant that was checked and the tenant's registered participants (`scheme:value`).", "type": "object", "properties": { "issuerParticipantId": { "type": "string" }, "registeredParticipantIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "issuerParticipantId", "registeredParticipantIds" ] } }, "required": [ "rule", "path", "message" ] } }, "report": { "type": "object", "properties": { "rulePackId": { "type": "string" }, "valid": { "type": "boolean" }, "layers": { "type": "array", "items": { "type": "object", "properties": { "layer": { "type": "string" }, "status": { "type": "string" } }, "required": [ "layer", "status" ] } }, "findings": { "type": "array", "items": { "type": "object", "properties": { "layer": { "type": "string" }, "severity": { "type": "string" }, "ruleId": { "type": "string" }, "location": { "type": "string" }, "test": { "type": "string" }, "message": { "type": "string" } }, "required": [ "layer", "severity", "location", "message" ] } } }, "required": [ "rulePackId", "valid", "layers", "findings" ] }, "invoiceId": { "type": "string" }, "invoice": { "type": "object", "additionalProperties": {} }, "sbdh": { "type": "object", "properties": { "sender": { "type": "string" }, "receiver": { "type": "string" } }, "required": [ "sender", "receiver" ] } }, "required": [ "index", "sourceRef", "status", "violations" ] } } }, "required": [ "summary", "items" ] }, "AsyncAcceptedDto": { "type": "object", "properties": { "messageId": { "type": "string" }, "statusUrl": { "type": "string" } }, "required": [ "messageId", "statusUrl" ] }, "JobStatusDto": { "type": "object", "properties": { "messageId": { "type": "string" }, "status": { "type": "string" }, "integrationId": { "type": "string", "nullable": true }, "result": {}, "error": { "type": "string", "nullable": true } }, "required": [ "messageId", "status", "integrationId", "result", "error" ] }, "WebhookDto": { "type": "object", "properties": { "backendTxId": { "type": "string", "minLength": 1 }, "contextHint": { "type": "object", "properties": { "profile": { "type": "string", "enum": [ "tax", "commercial" ] } } } }, "required": [ "backendTxId" ] }, "InboundAcceptedDto": { "type": "object", "properties": { "backendTxId": { "type": "string" }, "enqueued": { "type": "boolean" } }, "required": [ "backendTxId", "enqueued" ] }, "ReceiptDto": { "type": "object", "properties": { "backendTxId": { "type": "string", "minLength": 1 }, "tenantId": { "type": "string", "minLength": 1 }, "integrationId": { "type": "string", "minLength": 1 } }, "required": [ "backendTxId", "tenantId", "integrationId" ] }, "OutboundReceiptAcceptedDto": { "type": "object", "properties": { "backendTxId": { "type": "string" }, "reconciled": { "type": "string", "enum": [ "delivered", "failed", "pending", "unresolved" ] } }, "required": [ "backendTxId", "reconciled" ] }, "ReportingMlsDto": { "type": "object", "properties": { "tenantId": { "type": "string", "minLength": 1 }, "integrationId": { "type": "string", "minLength": 1 }, "corner": { "type": "string", "enum": [ "C5_C2", "C5_C3" ] }, "backendTxId": { "type": "string", "minLength": 1 }, "cdpReference": { "type": "string", "minLength": 1 }, "rawMls": { "type": "string", "minLength": 1 } }, "required": [ "tenantId", "integrationId", "corner", "backendTxId", "cdpReference", "rawMls" ] }, "ReportingMlsAcceptedDto": { "type": "object", "properties": { "cdpReference": { "type": "string" }, "reconciled": { "type": "string", "enum": [ "reported", "reporting-failed", "pending" ] } }, "required": [ "cdpReference", "reconciled" ] }, "SearchResultPageDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "tenantId": { "type": "string" }, "integrationId": { "type": "string" }, "invoiceId": { "type": "string" }, "uuid": { "type": "string" }, "issueDate": { "type": "string" }, "documentKind": { "type": "string" }, "typeCode": { "type": "string" }, "billingMode": { "type": "string", "enum": [ "standard", "self-billed", "unknown" ] }, "currencyCode": { "type": "string" }, "sellerName": { "type": "string" }, "sellerTrn": { "type": "string", "nullable": true }, "sellerEndpoint": { "type": "string" }, "buyerName": { "type": "string" }, "buyerTrn": { "type": "string", "nullable": true }, "buyerEndpoint": { "type": "string" }, "taxExclusiveAmount": { "type": "string" }, "taxTotalAmount": { "type": "string" }, "taxInclusiveAmount": { "type": "string" }, "aggregateOutcome": { "type": "string" }, "legStates": { "type": "object", "additionalProperties": { "type": "string" } }, "routeClass": { "type": "string", "nullable": true }, "direction": { "type": "string" }, "reportingStatus": { "type": "string", "nullable": true }, "reportingBlocked": { "type": "array", "items": { "type": "object", "properties": { "corner": { "type": "string" }, "reasonCode": { "type": "string" } }, "required": [ "corner", "reasonCode" ] } }, "authoritativeRef": { "type": "string" }, "projectionVersion": { "type": "number" } }, "required": [ "tenantId", "integrationId", "invoiceId", "uuid", "issueDate", "documentKind", "typeCode", "billingMode", "currencyCode", "sellerName", "sellerTrn", "sellerEndpoint", "buyerName", "buyerTrn", "buyerEndpoint", "taxExclusiveAmount", "taxTotalAmount", "taxInclusiveAmount", "aggregateOutcome", "legStates", "routeClass", "direction", "reportingStatus", "reportingBlocked", "authoritativeRef", "projectionVersion" ] } }, "facets": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" } }, "required": [ "value", "count" ] } } }, "nextCursor": { "type": "string", "nullable": true }, "total": { "type": "number" } }, "required": [ "items", "facets", "nextCursor", "total" ] }, "AuditPageDto": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "tenantId": { "type": "string" }, "seq": { "type": "number" }, "occurredAt": { "type": "string" }, "actor": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "id" ] }, "actorDisplay": { "type": "object", "properties": { "displayName": { "type": "string" }, "email": { "type": "string" } }, "required": [ "displayName", "email" ] }, "action": { "type": "string" }, "resource": { "type": "string" }, "outcome": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "prevHash": { "type": "string" }, "hash": { "type": "string" } }, "required": [ "tenantId", "seq", "occurredAt", "actor", "action", "resource", "outcome", "prevHash", "hash" ] } }, "nextCursor": { "type": "string", "nullable": true } }, "required": [ "entries", "nextCursor" ] }, "AuditVerifyDto": { "type": "object", "properties": { "valid": { "type": "boolean" }, "brokenAt": { "type": "number" }, "lastCheckpoint": { "type": "object", "properties": { "toSeq": { "type": "number" }, "checkpointHash": { "type": "string" }, "signer": { "type": "string" } }, "required": [ "toSeq", "checkpointHash", "signer" ], "nullable": true } }, "required": [ "valid", "lastCheckpoint" ] }, "CreateLegalHoldDto": { "type": "object", "properties": { "holdId": { "type": "string", "minLength": 1, "maxLength": 64 }, "fromOccurredAt": { "type": "string", "format": "date-time" }, "toOccurredAt": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ] }, "LegalHoldDto": { "type": "object", "properties": { "holdId": { "type": "string" }, "fromOccurredAt": { "type": "string", "nullable": true }, "toOccurredAt": { "type": "string", "nullable": true }, "reason": { "type": "string" } }, "required": [ "holdId", "fromOccurredAt", "toOccurredAt", "reason" ] }, "LegalHoldReleasedDto": { "type": "object", "properties": { "holdId": { "type": "string" }, "released": { "type": "boolean" } }, "required": [ "holdId", "released" ] }, "LegalHoldListDto": { "type": "object", "properties": { "holds": { "type": "array", "items": { "type": "object", "properties": { "holdId": { "type": "string" }, "fromOccurredAt": { "type": "string", "nullable": true }, "toOccurredAt": { "type": "string", "nullable": true }, "reason": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "holdId", "fromOccurredAt", "toOccurredAt", "reason", "createdAt" ] } } }, "required": [ "holds" ] }, "ArtifactResponseDto": { "type": "object", "properties": { "ublXml": { "type": "string" }, "sbdhXml": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "stored", "re-rendered" ] } }, "required": [ "ublXml", "sbdhXml", "source" ] }, "StoredInvoiceDto": { "type": "object", "properties": { "id": { "type": "string" }, "uuid": { "type": "string" }, "issueDate": { "type": "string" }, "documentKind": { "type": "string" }, "billingMode": { "type": "string" }, "typeCode": { "type": "string" }, "currencyCode": { "type": "string" }, "exchangeRate": { "type": "string" }, "transactionTypeCode": { "type": "string" }, "paymentDueDate": { "type": "string" }, "taxPointDate": { "type": "string" }, "businessProcessType": { "type": "string" }, "specificationIdentifier": { "type": "string" }, "paymentMeansTypeCode": { "description": "Payment means type code (IBT-081), mandatory. Closed list — PINT AE publishes its own UNCL4461 subset, \"Payment means codes used in AE\": 1 instrument not defined, 10 in cash, 20 cheque, 21 banker's draft, 30 credit transfer, 49 direct debit, 54 credit card, 55 debit card, 68 online payment service. Any other value is rejected with 422 INVALID_PAYMENT_MEANS_CODE naming the acceptable codes, including UNCL4461 codes such as 48 that the Schematron would take but the AE list does not contain; the same list applies to additionalPaymentMeans[].typeCode. Code 30 additionally requires payeeFinancialAccountId (IBT-084, ibr-192-ae).", "type": "string" }, "payeeFinancialAccountId": { "type": "string" }, "seller": { "type": "object", "properties": { "name": { "type": "string" }, "endpoint": { "type": "object", "properties": { "scheme": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "scheme", "value" ] }, "legalRegistrationId": { "type": "string" }, "legalRegistrationIdType": { "type": "string" }, "taxRegistrationId": { "type": "string" }, "taxSchemeCode": { "type": "string" }, "identifier": { "description": "Party identifier — IBT-046 Buyer identifier on the buyer, IBT-029 Seller identifier on the seller; emitted as cac:PartyIdentification/cbc:ID without a scheme. On a 0235 buyer address other than a TIN (the predefined 0235:9900000097 / 0235:9900000098) without the export flag, the buyer needs taxRegistrationId OR identifier (ibr-135-ae), else 422 BUYER_IDENTIFIER_REQUIRED at buyer.identifier.", "type": "string" }, "address": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "city": { "type": "string" }, "postalZone": { "type": "string" }, "countrySubdivision": { "description": "Country subdivision (IBT-039/054/079). When countryCode is AE this must be the emirate code — AUH, DXB, SHJ, AJM, UAQ, RAK or FUJ (IBR-128-AE); a name such as \"Dubai\" or a retired code such as \"DU\" is rejected with 422 AE_EMIRATE_CODE naming the code to use. Free text for other countries.", "type": "string" }, "countryCode": { "type": "string" } }, "required": [ "addressLine1", "city", "countrySubdivision", "countryCode" ] }, "authorityName": { "type": "string" } }, "required": [ "name", "endpoint", "legalRegistrationId", "legalRegistrationIdType", "address" ] }, "buyer": { "type": "object", "properties": { "name": { "type": "string" }, "endpoint": { "type": "object", "properties": { "scheme": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 } }, "required": [ "scheme", "value" ] }, "legalRegistrationId": { "type": "string" }, "legalRegistrationIdType": { "type": "string" }, "taxRegistrationId": { "type": "string" }, "taxSchemeCode": { "type": "string" }, "identifier": { "description": "Party identifier — IBT-046 Buyer identifier on the buyer, IBT-029 Seller identifier on the seller; emitted as cac:PartyIdentification/cbc:ID without a scheme. On a 0235 buyer address other than a TIN (the predefined 0235:9900000097 / 0235:9900000098) without the export flag, the buyer needs taxRegistrationId OR identifier (ibr-135-ae), else 422 BUYER_IDENTIFIER_REQUIRED at buyer.identifier.", "type": "string" }, "address": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "city": { "type": "string" }, "postalZone": { "type": "string" }, "countrySubdivision": { "description": "Country subdivision (IBT-039/054/079). When countryCode is AE this must be the emirate code — AUH, DXB, SHJ, AJM, UAQ, RAK or FUJ (IBR-128-AE); a name such as \"Dubai\" or a retired code such as \"DU\" is rejected with 422 AE_EMIRATE_CODE naming the code to use. Free text for other countries.", "type": "string" }, "countryCode": { "type": "string" } }, "required": [ "addressLine1", "city", "countrySubdivision", "countryCode" ] }, "authorityName": { "type": "string" } }, "required": [ "name", "endpoint", "legalRegistrationId", "legalRegistrationIdType", "address" ] }, "totals": { "type": "object", "properties": { "lineNetTotal": { "type": "string" }, "taxExclusiveAmount": { "type": "string" }, "taxTotalAmount": { "type": "string" }, "taxInclusiveAmount": { "type": "string" }, "allowanceTotalAmount": { "type": "string" }, "chargeTotalAmount": { "type": "string" }, "prepaidAmount": { "type": "string" }, "roundingAmount": { "type": "string" }, "amountDueForPayment": { "type": "string" }, "taxTotalAmountAed": { "type": "string" }, "taxInclusiveAmountAed": { "type": "string" } }, "required": [ "lineNetTotal", "taxExclusiveAmount", "taxTotalAmount", "taxInclusiveAmount", "amountDueForPayment" ] }, "taxBreakdown": { "type": "array", "items": { "type": "object", "properties": { "taxableAmount": { "type": "string" }, "taxAmount": { "type": "string" }, "categoryCode": { "type": "string" }, "rate": { "type": "string" }, "categoryExemptionReason": { "type": "string" }, "categoryExemptionReasonCode": { "type": "string" } }, "required": [ "taxableAmount", "taxAmount", "categoryCode", "rate" ] } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "string" }, "unitOfMeasureCode": { "type": "string" }, "netAmount": { "type": "string" }, "itemNetPrice": { "type": "string" }, "itemGrossPrice": { "type": "string" }, "itemPriceBaseQuantity": { "type": "string" }, "itemTaxCategoryCode": { "type": "string" }, "itemTaxRate": { "type": "string" }, "itemTaxExemptionReasonCode": { "description": "VAT exemption reason code (IBT-186), mandatory on an exempt (E) line. Closed list, one code per category of exempt supply in Article 46 of the VAT Decree-Law: DL8.46.1 certain financial services, DL8.46.2 supply of residential units (lease or sale), DL8.46.3 bare land, DL8.46.4 local passenger transport. Any other value is rejected with 422 INVALID_EXEMPTION_REASON_CODE naming the acceptable codes; the same list applies to taxBreakdown[].categoryExemptionReasonCode and to allowances[]/charges[].exemptionReasonCode. A free-text explanation belongs in itemTaxExemptionReason (IBT-185).", "type": "string" }, "itemTaxExemptionReason": { "type": "string" }, "vatLineAmountAed": { "type": "string" }, "lineAmountAed": { "type": "string" }, "itemName": { "type": "string" }, "itemDescription": { "type": "string" }, "standardItemIdentifier": { "type": "string" }, "commodityNatureCode": { "type": "string" }, "itemTypeCode": { "type": "string" }, "itemClassificationCode": { "type": "string" }, "serviceAccountingCode": { "type": "string" }, "batchNumber": { "type": "string" }, "allowances": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "reasonCode": { "type": "string" }, "reason": { "type": "string" }, "baseAmount": { "type": "string" }, "percentage": { "type": "string" } }, "required": [ "amount" ] } }, "charges": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "reasonCode": { "type": "string" }, "reason": { "type": "string" }, "baseAmount": { "type": "string" }, "percentage": { "type": "string" } }, "required": [ "amount" ] } } }, "required": [ "id", "quantity", "unitOfMeasureCode", "netAmount", "itemNetPrice", "itemGrossPrice", "itemPriceBaseQuantity", "itemTaxCategoryCode", "itemTaxRate", "itemName", "itemDescription" ] } }, "precedingInvoiceReferences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "issueDate": { "type": "string" } }, "required": [ "id" ] } }, "creditNoteReasonCode": { "description": "Adjustment ground: DL8.61.1.A cancellation; B nature/tax-treatment change; C consideration change; D return AND consideration repaid; E tax or treatment applied in error. VD is the separate volume discount code. VAT Law Art. 61(1), ADR-0238.", "type": "string" }, "adjustment": { "description": "AXS-internal credit-note correction event, YYYY-MM-DD; never sent to Peppol. Ground is creditNoteReasonCode. For DL8.61.1.D both return and repayment must have occurred. VAT Law Art. 62(2): 14 days excluding event day; a weekend or official Federal Government holiday endpoint moves to the next Business Day. Missing event is not assessable; lateness is advisory, never 422.", "type": "object", "properties": { "eventDate": { "type": "string" } }, "required": [ "eventDate" ] }, "beneficiary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ] }, "principal": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id" ] }, "invoicingPeriod": { "type": "object", "properties": { "startDate": { "type": "string" }, "endDate": { "type": "string" }, "frequencyCode": { "type": "string" } }, "required": [ "startDate", "endDate" ] }, "delivery": { "type": "object", "properties": { "address": { "type": "object", "properties": { "addressLine1": { "type": "string" }, "city": { "type": "string" }, "postalZone": { "type": "string" }, "countrySubdivision": { "description": "Country subdivision (IBT-039/054/079). When countryCode is AE this must be the emirate code — AUH, DXB, SHJ, AJM, UAQ, RAK or FUJ (IBR-128-AE); a name such as \"Dubai\" or a retired code such as \"DU\" is rejected with 422 AE_EMIRATE_CODE naming the code to use. Free text for other countries.", "type": "string" }, "countryCode": { "type": "string" } }, "required": [ "addressLine1", "city", "countrySubdivision", "countryCode" ] }, "actualDeliveryDate": { "description": "Actual delivery date (IBT-072), YYYY-MM-DD, on any scenario. The address is only required on e-commerce/export (SCENARIO_DELIVERY_REQUIRED); a malformed date is 422 DELIVERY_DATE_FORMAT (ibr-073).", "type": "string" }, "deliverToPartyId": { "type": "string" }, "deliverToPartyName": { "type": "string" } } }, "allowances": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "reasonCode": { "type": "string" }, "reason": { "type": "string" }, "baseAmount": { "type": "string" }, "percentage": { "type": "string" }, "taxCategoryCode": { "type": "string" }, "taxRate": { "type": "string" }, "exemptionReasonCode": { "type": "string" }, "exemptionReason": { "type": "string" } }, "required": [ "amount", "taxCategoryCode" ] } }, "charges": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string" }, "reasonCode": { "type": "string" }, "reason": { "type": "string" }, "baseAmount": { "type": "string" }, "percentage": { "type": "string" }, "taxCategoryCode": { "type": "string" }, "taxRate": { "type": "string" }, "exemptionReasonCode": { "type": "string" }, "exemptionReason": { "type": "string" } }, "required": [ "amount", "taxCategoryCode" ] } }, "invoiceNote": { "type": "string" }, "incoterms": { "type": "string" }, "paymentTermsNote": { "type": "string" }, "additionalPaymentMeans": { "type": "array", "items": { "type": "object", "properties": { "typeCode": { "type": "string" }, "payeeFinancialAccountId": { "type": "string" } }, "required": [ "typeCode" ] } }, "buyerReference": { "description": "Buyer reference (IBT-010, cbc:BuyerReference): the buyer's own identifier (e.g. cost centre) to be quoted back. Free text; must not be blank when present (422 DOCUMENT_REFERENCE_BLANK).", "type": "string" }, "orderReference": { "description": "Purchase order reference (IBT-013, cac:OrderReference/cbc:ID): the buyer's order number. Free text; must not be blank when present.", "type": "string" }, "contractReference": { "description": "Contract reference (IBT-012, cac:ContractDocumentReference/cbc:ID). Free text, at most one (ibr-094); must not be blank when present.", "type": "string" }, "attachments": { "description": "Additional supporting documents (IBG-24): each one has an id and an embedded file (base64 + mimeCode + filename) and/or an external URI. Allowed MIME codes: application/pdf, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/xml, application/vnd.oasis.opendocument.spreadsheet — the pack's ibr-cl-24 list (application/pdf, image/png, image/jpeg, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/xml, application/vnd.oasis.opendocument.spreadsheet) minus image/png and image/jpeg: the UAE rules allow no QR code or barcode on the electronic invoice ([G] 5.3), and an image could carry one, so an image attachment is 422 ATTACHMENT_IMAGE_REFUSED at attachments[i].embedded.mimeCode. At most 10 documents, their decoded files totalling at most 512 KiB (the base64 body must also fit the 1 MiB request limit). Every embedded file is malware-scanned before admission: an infected file is 422 ATTACHMENT_MALWARE and quarantined, a scan that cannot run is 503. A refused type or size is 422 ATTACHMENT_MIME / ATTACHMENT_SIZE at the field.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Supporting document reference (IBT-122); not blank (ibr-052).", "type": "string" }, "description": { "description": "Supporting document description (IBT-123).", "type": "string" }, "externalUri": { "description": "External document location (IBT-124): an absolute http(s) URI, at most 2048 characters.", "type": "string" }, "embedded": { "description": "Attached document (IBT-125), embedded as base64.", "type": "object", "properties": { "content": { "description": "The file content, base64 (RFC 4648).", "type": "string" }, "mimeCode": { "description": "MIME code (IBT-125-1): one of application/pdf, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/xml, application/vnd.oasis.opendocument.spreadsheet — the ibr-cl-24 list without its two image types, which an issued invoice may not carry ([G] 5.3).", "type": "string" }, "filename": { "description": "File name (IBT-125-2), required (ibr-075).", "type": "string" } }, "required": [ "content", "mimeCode", "filename" ] } }, "required": [ "id" ] } }, "paymentReceiptDate": { "description": "Date payment for the business transaction was received, YYYY-MM-DD. AXS-internal: never emitted to the Peppol network. Read only by the advisory issuing-deadline assessment, which counts the 14 days from the EARLIEST of the date of supply, the actual delivery date and this date (MD 243/2025 Art. 1 and 6(5)). A malformed date is 422 PAYMENT_RECEIPT_DATE_FORMAT.", "type": "string" }, "selfBillingAgreement": { "description": "AXS-internal, set by AXS at admission — never accepted on input, never sent to the Peppol network (PINT-AE has no element for it). On a self-billed document: the self-billing agreement on record for the supplier in the tenant's partner master (reference, date concluded, validity, validTo absent = open-ended). Absent when none was on record.", "type": "object", "properties": { "reference": { "type": "string" }, "date": { "type": "string" }, "validFrom": { "type": "string" }, "validTo": { "type": "string" } }, "required": [ "reference", "date", "validFrom" ] } }, "required": [ "id", "uuid", "issueDate", "documentKind", "billingMode", "typeCode", "currencyCode", "transactionTypeCode", "paymentDueDate", "businessProcessType", "specificationIdentifier", "paymentMeansTypeCode", "seller", "buyer", "totals", "taxBreakdown", "lines" ] }, "ResendResultDto": { "type": "object", "properties": { "integrationId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING" ] }, "attempts": { "type": "number" } }, "required": [ "integrationId", "status", "attempts" ] }, "ProvisionDto": { "type": "object", "properties": { "scheme": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "endpointId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "profileIds": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "businessName": { "type": "string", "minLength": 1 }, "countryCode": { "type": "string" } }, "required": [ "scheme", "value", "endpointId", "profileIds", "businessName", "countryCode" ] }, "OnboardingStatusDto": { "type": "object", "properties": { "scheme": { "type": "string" }, "value": { "type": "string" }, "status": { "type": "string", "enum": [ "NONE", "PENDING", "REGISTERED", "DELISTED" ] }, "endpointId": { "type": "number", "nullable": true }, "profileIds": { "type": "array", "items": { "type": "number" }, "nullable": true }, "businessName": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "regDataVersion": { "type": "number", "nullable": true }, "smpProvider": { "type": "string", "nullable": true }, "lastReconciledAt": { "type": "string", "nullable": true } }, "required": [ "scheme", "value", "status", "endpointId", "profileIds", "businessName", "countryCode", "regDataVersion", "smpProvider", "lastReconciledAt" ] }, "OnboardingViolationsDto": { "type": "object", "properties": { "violations": { "type": "array", "items": { "type": "object", "properties": { "rule": { "description": "Rule code: `participant-id`, `tin-verification`, `tax-group-representative-tin` or `envelope-shape`.", "type": "string" }, "path": { "description": "The offending body field, or `value` for the participant id.", "type": "string" }, "message": { "description": "Informational English text; branch on `rule`.", "type": "string" } }, "required": [ "rule", "path", "message" ] } } }, "required": [ "violations" ] }, "UpdateRegistrationDto": { "type": "object", "properties": { "endpointId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true }, "profileIds": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 0, "exclusiveMinimum": true } }, "businessName": { "type": "string", "minLength": 1 }, "countryCode": { "type": "string" } }, "required": [ "endpointId", "profileIds", "businessName", "countryCode" ] }, "ReconcileResultDto": { "type": "object", "properties": { "scheme": { "type": "string" }, "value": { "type": "string" }, "status": { "type": "string", "enum": [ "NONE", "PENDING", "REGISTERED", "DELISTED" ] }, "endpointId": { "type": "number", "nullable": true }, "profileIds": { "type": "array", "items": { "type": "number" }, "nullable": true }, "businessName": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "regDataVersion": { "type": "number", "nullable": true }, "smpProvider": { "type": "string", "nullable": true }, "lastReconciledAt": { "type": "string", "nullable": true }, "smpPublished": { "type": "boolean" }, "drift": { "type": "boolean" }, "smlPublished": { "description": "SML NAPTR presence (AXS-113): `not-checked` = no SML zone configured; `unknown` = DNS failure (never read as absent).", "type": "string", "enum": [ "absent", "present", "unknown", "not-checked" ] } }, "required": [ "scheme", "value", "status", "endpointId", "profileIds", "businessName", "countryCode", "regDataVersion", "smpProvider", "lastReconciledAt", "smpPublished", "drift", "smlPublished" ] }, "DelistResultDto": { "type": "object", "properties": { "scheme": { "type": "string" }, "value": { "type": "string" }, "status": { "type": "string", "enum": [ "NONE", "PENDING", "REGISTERED", "DELISTED" ] }, "endpointId": { "type": "number", "nullable": true }, "profileIds": { "type": "array", "items": { "type": "number" }, "nullable": true }, "businessName": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "regDataVersion": { "type": "number", "nullable": true }, "smpProvider": { "type": "string", "nullable": true }, "lastReconciledAt": { "type": "string", "nullable": true }, "propagation": { "type": "object", "properties": { "smp": { "description": "SMP read-back after the DELETE.", "type": "string", "enum": [ "unpublished", "still-published", "unknown" ] }, "sml": { "description": "SML NAPTR presence (AXS-113): `not-checked` = no SML zone configured; `unknown` = DNS failure (never read as absent).", "type": "string", "enum": [ "absent", "present", "unknown", "not-checked" ] }, "verdict": { "description": "`propagated` only when both legs are measured gone; `sml-pending` = the SMP record is gone but the SML NAPTR still resolves (asynchronous DNS — re-measure via reconcile); `failed` = the SMP still publishes the participant.", "type": "string", "enum": [ "propagated", "sml-pending", "smp-confirmed", "failed", "unverified" ] }, "checkedAt": { "type": "string" } }, "required": [ "smp", "sml", "verdict", "checkedAt" ] } }, "required": [ "scheme", "value", "status", "endpointId", "profileIds", "businessName", "countryCode", "regDataVersion", "smpProvider", "lastReconciledAt", "propagation" ] }, "RegistrationRequestBodyDto": { "type": "object", "properties": { "emarataxSelectionConfirmed": { "type": "boolean" } }, "required": [ "emarataxSelectionConfirmed" ] }, "RegistrationViewDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not-requested", "requested", "in-progress", "rejected", "registered" ] }, "requestedAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "rejectionReason": { "type": "string", "nullable": true }, "expectedBy": { "type": "string", "nullable": true }, "contact": { "type": "string", "nullable": true } }, "required": [ "status", "requestedAt", "updatedAt", "rejectionReason", "expectedBy", "contact" ] }, "DashboardSummaryDto": { "type": "object", "properties": { "todayVolume": { "type": "object", "properties": { "inbound": { "type": "number" }, "outbound": { "type": "number" } }, "required": [ "inbound", "outbound" ] }, "outcome": { "type": "object", "properties": { "compliant": { "type": "number" }, "partial": { "type": "number" }, "failed": { "type": "number" }, "total": { "type": "number" } }, "required": [ "compliant", "partial", "failed", "total" ] }, "c5": { "type": "object", "properties": { "reported": { "type": "number" }, "reportingFailed": { "type": "number" }, "pending": { "type": "number" }, "blocked": { "type": "number" } }, "required": [ "reported", "reportingFailed", "pending", "blocked" ] }, "freeTier": { "type": "object", "properties": { "limit": { "type": "number" }, "used": { "type": "number" }, "remaining": { "type": "number" }, "periodStart": { "type": "string" }, "periodEnd": { "type": "string" } }, "required": [ "limit", "used", "remaining", "periodStart", "periodEnd" ] }, "asOf": { "type": "string" } }, "required": [ "todayVolume", "outcome", "c5", "freeTier", "asOf" ] }, "OnboardingChecklistDto": { "type": "object", "properties": { "steps": { "type": "object", "properties": { "profile": { "type": "boolean" }, "partner": { "type": "boolean" }, "product": { "type": "boolean" }, "invoice": { "type": "boolean" } }, "required": [ "profile", "partner", "product", "invoice" ] }, "completed": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 4, "exclusiveMaximum": false }, "total": { "type": "number", "minimum": 4, "maximum": 4 }, "asOf": { "type": "string" } }, "required": [ "steps", "completed", "total", "asOf" ] }, "OnboardingGuideDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not-started", "active", "skipped", "done" ] }, "updatedAt": { "type": "string", "nullable": true } }, "required": [ "status", "updatedAt" ] }, "OnboardingGuideBodyDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "skipped", "done" ] } }, "required": [ "status" ] }, "CurrencyListDto": { "type": "object", "properties": { "currencies": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "minorUnits": { "type": "number" } }, "required": [ "code", "name", "minorUnits" ] } } }, "required": [ "currencies" ] }, "CountryListDto": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "object", "properties": { "alpha2": { "type": "string" }, "name": { "type": "string" } }, "required": [ "alpha2", "name" ] } } }, "required": [ "countries" ] }, "NotificationPageDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "integrationId": { "type": "string" }, "type": { "type": "string" }, "detail": { "type": "object", "properties": { "reason": { "type": "string" }, "field": { "type": "string", "nullable": true }, "count": { "type": "number" } }, "required": [ "reason" ], "nullable": true }, "context": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "invoiceNumber": { "type": "string", "nullable": true }, "partnerName": { "type": "string", "nullable": true }, "amount": { "type": "string", "nullable": true }, "currencyCode": { "type": "string", "nullable": true } }, "required": [ "direction", "invoiceNumber", "partnerName", "amount", "currencyCode" ], "nullable": true }, "createdAt": { "type": "string" }, "readAt": { "type": "string", "nullable": true } }, "required": [ "id", "integrationId", "type", "detail", "context", "createdAt", "readAt" ] } }, "nextCursor": { "type": "string", "nullable": true }, "unreadCount": { "type": "number" } }, "required": [ "items", "nextCursor", "unreadCount" ] }, "MarkReadDto": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } } } }, "ProfileResponseDto": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "legalName": { "type": "string" }, "trn": { "type": "string" }, "addressLine1": { "type": "string" }, "city": { "type": "string" }, "postalZone": { "type": "string" }, "countrySubdivision": { "type": "string" }, "countryCode": { "type": "string" }, "authorityName": { "type": "string" }, "legalRegistrationId": { "type": "string" }, "legalRegistrationIdType": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "legalName", "trn", "addressLine1", "city", "postalZone", "countrySubdivision", "countryCode", "authorityName", "legalRegistrationId", "legalRegistrationIdType", "updatedAt" ], "nullable": true }, "participantRegistered": { "description": "Deprecated (AXS-301): equals peppolRegistration.status === 'registered'.", "type": "boolean", "deprecated": true }, "peppolRegistration": { "type": "object", "properties": { "status": { "description": "registered: the TRN-derived participant is one of the tenant's own; mismatch: the tenant has registered participants, but not the TRN-derived one; none: the tenant has no participant, or there is no TRN to compare (no profile yet).", "type": "string", "enum": [ "registered", "mismatch", "none" ] }, "derivedParticipantId": { "description": "`0235:` + the first 10 TRN digits; null without a 15-digit profile TRN.", "type": "string", "nullable": true }, "registeredParticipantIds": { "description": "The tenant's own registered participants as `scheme:value`, sorted.", "type": "array", "items": { "type": "string" } } }, "required": [ "status", "derivedParticipantId", "registeredParticipantIds" ] }, "registration": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not-requested", "requested", "in-progress", "rejected", "registered" ] }, "requestedAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "rejectionReason": { "type": "string", "nullable": true }, "expectedBy": { "type": "string", "nullable": true }, "contact": { "type": "string", "nullable": true } }, "required": [ "status", "requestedAt", "updatedAt", "rejectionReason", "expectedBy", "contact" ] } }, "required": [ "profile", "participantRegistered", "peppolRegistration", "registration" ] }, "ProfileBodyDto": { "type": "object", "properties": { "legalName": { "type": "string", "minLength": 1 }, "trn": { "type": "string", "pattern": "^1\\d{12}03$" }, "addressLine1": { "type": "string", "minLength": 1 }, "city": { "type": "string", "minLength": 1 }, "postalZone": { "type": "string", "default": "" }, "countrySubdivision": { "type": "string", "default": "" }, "countryCode": { "type": "string", "default": "AE" }, "authorityName": { "type": "string", "default": "" }, "legalRegistrationId": { "type": "string", "default": "" }, "legalRegistrationIdType": { "type": "string", "default": "" } }, "required": [ "legalName", "trn", "addressLine1", "city" ] }, "MasterDataViolationsDto": { "type": "object", "properties": { "violations": { "type": "array", "items": { "type": "object", "properties": { "rule": { "description": "Stable rule code (for example `MANDATORY_FIELD`, `INVALID_TRN`, `INVALID_EMIRATE`, `LEGAL_ID_TYPE`, `INVALID_PRICE`); branch and localise on this, not on `message`.", "type": "string" }, "path": { "description": "The offending body field (`name`, `trn`, `countrySubdivision`, `netPrice`).", "type": "string" }, "message": { "description": "Informational English text, for logs and developers; not a UI string.", "type": "string" } }, "required": [ "rule", "path", "message" ] } } }, "required": [ "violations" ] }, "InvoiceDraftPageDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 2147483646, "exclusiveMaximum": false }, "schemaVersion": { "type": "number", "minimum": 1, "maximum": 1 }, "title": { "type": "string", "maxLength": 200 }, "id": { "type": "string", "format": "uuid" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "version", "schemaVersion", "title", "id", "updatedAt" ] } }, "total": { "type": "integer" } }, "required": [ "items", "total" ] }, "InvoiceDraftDto": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 2147483646, "exclusiveMaximum": false }, "schemaVersion": { "type": "number", "minimum": 1, "maximum": 1 }, "title": { "type": "string", "maxLength": 200 }, "id": { "type": "string", "format": "uuid" }, "updatedAt": { "type": "string", "format": "date-time" }, "form": { "type": "object", "additionalProperties": {} } }, "required": [ "version", "schemaVersion", "title", "id", "updatedAt", "form" ] }, "InvoiceDraftBodyDto": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 0, "exclusiveMinimum": false, "maximum": 2147483646, "exclusiveMaximum": false }, "schemaVersion": { "type": "number", "minimum": 1, "maximum": 1 }, "title": { "type": "string", "maxLength": 200 }, "form": { "type": "object", "additionalProperties": {} } }, "required": [ "version", "schemaVersion", "title", "form" ] }, "InvoiceDraftDeletedDto": { "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ] }, "NumberSeriesListDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "pattern": { "type": "string" }, "documentKinds": { "type": "array", "items": { "type": "string", "enum": [ "tax-invoice", "tax-credit-note", "commercial-invoice", "commercial-credit-note" ] } }, "resetYearly": { "type": "boolean" }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "pattern", "documentKinds", "resetYearly", "active", "createdAt", "updatedAt" ] } } }, "required": [ "items" ] }, "CreateNumberSeriesDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "pattern": { "description": "Literal characters (A-Z a-z 0-9 - / _ .) plus exactly one {SEQ} or {SEQ:n} (n = 1..12, zero padding) and at most one {YYYY} (issue-date year). A yearly restart requires {YYYY}.", "type": "string", "maxLength": 64 }, "documentKinds": { "description": "Either invoice kinds or credit-note kinds — credit notes run in their own series", "type": "array", "minItems": 1, "maxItems": 4, "items": { "type": "string", "enum": [ "tax-invoice", "tax-credit-note", "commercial-invoice", "commercial-credit-note" ] } }, "resetYearly": { "type": "boolean" } }, "required": [ "name", "pattern", "documentKinds", "resetYearly" ] }, "NumberSeriesDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "pattern": { "type": "string" }, "documentKinds": { "type": "array", "items": { "type": "string", "enum": [ "tax-invoice", "tax-credit-note", "commercial-invoice", "commercial-credit-note" ] } }, "resetYearly": { "type": "boolean" }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "pattern", "documentKinds", "resetYearly", "active", "createdAt", "updatedAt" ] }, "UpdateNumberSeriesDto": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "active": { "type": "boolean" } } }, "NumberSeriesNextDto": { "type": "object", "properties": { "seriesId": { "type": "string", "format": "uuid" }, "number": { "description": "The next free number — a suggestion; nothing is reserved", "type": "string" }, "sequence": { "type": "integer" }, "period": { "description": "Counting period: the issue-date year, or \"all\"", "type": "string" } }, "required": [ "seriesId", "number", "sequence", "period" ] }, "NumberSeriesAllocationPageDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "position": { "description": "Allocation order within the tenant (ascending = earlier)", "type": "string" }, "kind": { "type": "string", "enum": [ "issued", "skipped", "override" ] }, "number": { "type": "string" }, "sequence": { "type": "integer", "nullable": true }, "period": { "type": "string" }, "integrationId": { "type": "string", "nullable": true }, "expectedNumber": { "type": "string", "nullable": true }, "actorId": { "type": "string" }, "allocatedAt": { "type": "string", "format": "date-time" } }, "required": [ "position", "kind", "number", "sequence", "period", "integrationId", "expectedNumber", "actorId", "allocatedAt" ] } }, "total": { "type": "integer" } }, "required": [ "items", "total" ] }, "PartnerPageDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "trn": { "type": "string" }, "endpointScheme": { "type": "string" }, "endpointValue": { "type": "string" }, "addressLine1": { "type": "string" }, "city": { "type": "string" }, "postalZone": { "type": "string" }, "countrySubdivision": { "type": "string" }, "countryCode": { "type": "string" }, "authorityName": { "type": "string" }, "legalRegistrationId": { "type": "string" }, "legalRegistrationIdType": { "type": "string" }, "selfBillingAgreement": { "type": "object", "properties": { "reference": { "type": "string" }, "date": { "type": "string" }, "validFrom": { "type": "string" }, "validTo": { "type": "string" }, "note": { "type": "string" } }, "required": [ "reference", "date", "validFrom", "validTo", "note" ], "nullable": true }, "peppolStatus": { "type": "string" }, "peppolCheckedAt": { "type": "string", "nullable": true }, "lastUsedAt": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "trn", "endpointScheme", "endpointValue", "addressLine1", "city", "postalZone", "countrySubdivision", "countryCode", "authorityName", "legalRegistrationId", "legalRegistrationIdType", "selfBillingAgreement", "peppolStatus", "peppolCheckedAt", "lastUsedAt", "active", "updatedAt" ] } }, "total": { "type": "number" } }, "required": [ "items", "total" ] }, "PartnerDto": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "trn": { "type": "string" }, "endpointScheme": { "type": "string" }, "endpointValue": { "type": "string" }, "addressLine1": { "type": "string" }, "city": { "type": "string" }, "postalZone": { "type": "string" }, "countrySubdivision": { "type": "string" }, "countryCode": { "type": "string" }, "authorityName": { "type": "string" }, "legalRegistrationId": { "type": "string" }, "legalRegistrationIdType": { "type": "string" }, "selfBillingAgreement": { "type": "object", "properties": { "reference": { "type": "string" }, "date": { "type": "string" }, "validFrom": { "type": "string" }, "validTo": { "type": "string" }, "note": { "type": "string" } }, "required": [ "reference", "date", "validFrom", "validTo", "note" ], "nullable": true }, "peppolStatus": { "type": "string" }, "peppolCheckedAt": { "type": "string", "nullable": true }, "lastUsedAt": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "trn", "endpointScheme", "endpointValue", "addressLine1", "city", "postalZone", "countrySubdivision", "countryCode", "authorityName", "legalRegistrationId", "legalRegistrationIdType", "selfBillingAgreement", "peppolStatus", "peppolCheckedAt", "lastUsedAt", "active", "updatedAt" ] }, "PartnerBodyDto": { "type": "object", "properties": { "name": { "type": "string" }, "trn": { "type": "string", "default": "" }, "endpointScheme": { "type": "string", "default": "0235" }, "endpointValue": { "type": "string", "default": "" }, "addressLine1": { "type": "string", "default": "" }, "city": { "type": "string", "default": "" }, "postalZone": { "type": "string", "default": "" }, "countrySubdivision": { "type": "string", "default": "" }, "countryCode": { "type": "string", "default": "AE" }, "authorityName": { "type": "string", "default": "" }, "legalRegistrationId": { "type": "string", "default": "" }, "legalRegistrationIdType": { "type": "string", "default": "" }, "selfBillingAgreement": { "description": "Self-billing agreement with this partner (the supplier the tenant self-bills). Optional; when present, reference, date and validFrom are required. A self-billed document issued without one in force gets an advisory warning, never a rejection.", "type": "object", "properties": { "reference": { "type": "string", "default": "" }, "date": { "description": "Date the agreement was concluded, YYYY-MM-DD.", "type": "string", "default": "" }, "validFrom": { "description": "First day covered, YYYY-MM-DD (inclusive).", "type": "string", "default": "" }, "validTo": { "description": "Last day covered, YYYY-MM-DD (inclusive); empty = open-ended.", "type": "string", "default": "" }, "note": { "type": "string", "default": "" } }, "nullable": true, "default": null } }, "required": [ "name" ] }, "PartnerConflictDto": { "type": "object", "properties": { "error": { "type": "string" }, "existingId": { "type": "string" } }, "required": [ "error", "existingId" ] }, "PartnerDeactivatedDto": { "type": "object", "properties": { "id": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "active" ] }, "PeppolVerifyDto": { "type": "object", "properties": { "registered": { "type": "boolean" }, "available": { "type": "boolean" }, "stale": { "type": "boolean" }, "checkedAt": { "type": "string", "nullable": true } }, "required": [ "registered", "available", "stale", "checkedAt" ] }, "PeppolVerifyViolationsDto": { "type": "object", "properties": { "violations": { "type": "array", "items": { "type": "object", "properties": { "rule": { "description": "Rule code; `INVALID_TRN` when `trn` is absent, repeated or not a UAE TRN (15 digits, starting with 1, ending with 03 — PINT AE ibr-132-ae).", "type": "string" }, "path": { "description": "The offending query parameter (`trn`).", "type": "string" }, "message": { "type": "string" } }, "required": [ "rule", "path", "message" ] } } }, "required": [ "violations" ] }, "ProductPageDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "unitCode": { "type": "string" }, "netPrice": { "type": "string" }, "currencyCode": { "type": "string" }, "taxCategoryCode": { "type": "string" }, "taxRate": { "type": "string" }, "standardItemIdentifier": { "type": "string" }, "commodityNatureCode": { "type": "string" }, "itemTypeCode": { "type": "string" }, "itemClassificationCode": { "type": "string" }, "serviceAccountingCode": { "type": "string" }, "lastUsedAt": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "updatedAt": { "type": "string" } }, "required": [ "id", "sku", "name", "description", "unitCode", "netPrice", "currencyCode", "taxCategoryCode", "taxRate", "standardItemIdentifier", "commodityNatureCode", "itemTypeCode", "itemClassificationCode", "serviceAccountingCode", "lastUsedAt", "active", "updatedAt" ] } }, "total": { "type": "number" } }, "required": [ "items", "total" ] }, "ProductDto": { "type": "object", "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "unitCode": { "type": "string" }, "netPrice": { "type": "string" }, "currencyCode": { "type": "string" }, "taxCategoryCode": { "type": "string" }, "taxRate": { "type": "string" }, "standardItemIdentifier": { "type": "string" }, "commodityNatureCode": { "type": "string" }, "itemTypeCode": { "type": "string" }, "itemClassificationCode": { "type": "string" }, "serviceAccountingCode": { "type": "string" }, "lastUsedAt": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "updatedAt": { "type": "string" } }, "required": [ "id", "sku", "name", "description", "unitCode", "netPrice", "currencyCode", "taxCategoryCode", "taxRate", "standardItemIdentifier", "commodityNatureCode", "itemTypeCode", "itemClassificationCode", "serviceAccountingCode", "lastUsedAt", "active", "updatedAt" ] }, "ProductBodyDto": { "type": "object", "properties": { "sku": { "type": "string", "default": "" }, "name": { "type": "string" }, "description": { "type": "string", "default": "" }, "unitCode": { "type": "string", "default": "H87" }, "netPrice": { "type": "string", "default": "0.00" }, "currencyCode": { "type": "string", "default": "AED" }, "taxCategoryCode": { "type": "string", "default": "S" }, "standardItemIdentifier": { "type": "string", "default": "" }, "commodityNatureCode": { "type": "string", "default": "" }, "itemTypeCode": { "type": "string", "default": "" }, "itemClassificationCode": { "type": "string", "default": "" }, "serviceAccountingCode": { "type": "string", "default": "" } }, "required": [ "name" ] }, "ProductConflictDto": { "type": "object", "properties": { "error": { "type": "string" }, "existingId": { "type": "string" } }, "required": [ "error", "existingId" ] }, "ProductDeactivatedDto": { "type": "object", "properties": { "id": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "active" ] }, "ApiClientListDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "clientId": { "type": "string" }, "displayName": { "type": "string" }, "purpose": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "createdBy": { "type": "string" }, "lastRotatedAt": { "type": "string", "nullable": true }, "rotatedBy": { "type": "string", "nullable": true }, "revokedAt": { "type": "string", "nullable": true }, "revokedBy": { "type": "string", "nullable": true } }, "required": [ "clientId", "displayName", "purpose", "scopes", "status", "createdAt", "createdBy", "lastRotatedAt", "rotatedBy", "revokedAt", "revokedBy" ] } }, "activeCount": { "type": "number" }, "maxPerTenant": { "type": "number" } }, "required": [ "items", "activeCount", "maxPerTenant" ] }, "CreateApiClientBodyDto": { "type": "object", "properties": { "displayName": { "type": "string" }, "purpose": { "type": "string", "enum": [ "erp-ingest", "audit-read" ] } }, "required": [ "displayName", "purpose" ] }, "ApiClientSecretDto": { "type": "object", "properties": { "clientId": { "type": "string" }, "displayName": { "type": "string" }, "purpose": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "createdBy": { "type": "string" }, "lastRotatedAt": { "type": "string", "nullable": true }, "rotatedBy": { "type": "string", "nullable": true }, "revokedAt": { "type": "string", "nullable": true }, "revokedBy": { "type": "string", "nullable": true }, "secret": { "type": "string" } }, "required": [ "clientId", "displayName", "purpose", "scopes", "status", "createdAt", "createdBy", "lastRotatedAt", "rotatedBy", "revokedAt", "revokedBy", "secret" ] }, "ApiClientDto": { "type": "object", "properties": { "clientId": { "type": "string" }, "displayName": { "type": "string" }, "purpose": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "createdBy": { "type": "string" }, "lastRotatedAt": { "type": "string", "nullable": true }, "rotatedBy": { "type": "string", "nullable": true }, "revokedAt": { "type": "string", "nullable": true }, "revokedBy": { "type": "string", "nullable": true } }, "required": [ "clientId", "displayName", "purpose", "scopes", "status", "createdAt", "createdBy", "lastRotatedAt", "rotatedBy", "revokedAt", "revokedBy" ] }, "TenantUserListDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "invitedBy": { "type": "string" }, "invitedAt": { "type": "string" }, "lastInviteSentAt": { "type": "string", "nullable": true }, "activatedAt": { "type": "string", "nullable": true }, "disabledAt": { "type": "string", "nullable": true }, "disabledBy": { "type": "string", "nullable": true } }, "required": [ "id", "email", "displayName", "role", "status", "invitedBy", "invitedAt", "lastInviteSentAt", "activatedAt", "disabledAt", "disabledBy" ] } }, "adminCount": { "type": "number" } }, "required": [ "items", "adminCount" ] }, "InviteTenantUserBodyDto": { "type": "object", "properties": { "email": { "type": "string" }, "displayName": { "type": "string" }, "role": { "type": "string", "enum": [ "tenant-admin", "tenant-user", "auditor" ] } }, "required": [ "email", "displayName", "role" ] }, "TenantUserInviteResultDto": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "invitedBy": { "type": "string" }, "invitedAt": { "type": "string" }, "lastInviteSentAt": { "type": "string", "nullable": true }, "activatedAt": { "type": "string", "nullable": true }, "disabledAt": { "type": "string", "nullable": true }, "disabledBy": { "type": "string", "nullable": true } }, "required": [ "id", "email", "displayName", "role", "status", "invitedBy", "invitedAt", "lastInviteSentAt", "activatedAt", "disabledAt", "disabledBy" ] }, "linked": { "type": "boolean" } }, "required": [ "user", "linked" ] }, "TenantUserConflictDto": { "type": "object", "properties": { "error": { "type": "string" }, "existingId": { "type": "string" } }, "required": [ "error" ] }, "TenantUserUnavailableDto": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] }, "TenantUserDto": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "role": { "type": "string" }, "status": { "type": "string" }, "invitedBy": { "type": "string" }, "invitedAt": { "type": "string" }, "lastInviteSentAt": { "type": "string", "nullable": true }, "activatedAt": { "type": "string", "nullable": true }, "disabledAt": { "type": "string", "nullable": true }, "disabledBy": { "type": "string", "nullable": true } }, "required": [ "id", "email", "displayName", "role", "status", "invitedBy", "invitedAt", "lastInviteSentAt", "activatedAt", "disabledAt", "disabledBy" ] }, "ChangeTenantUserRoleBodyDto": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "tenant-admin", "tenant-user", "auditor" ] } }, "required": [ "role" ] }, "CallbackConfigDto": { "type": "object", "properties": { "url": { "type": "string" }, "enabled": { "type": "boolean" }, "version": { "type": "number" }, "configured": { "type": "boolean" }, "available": { "type": "boolean" }, "updatedAt": { "type": "string", "nullable": true } }, "required": [ "url", "enabled", "version", "configured", "available", "updatedAt" ] }, "CallbackUpdateDto": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048 }, "enabled": { "type": "boolean" }, "expectedVersion": { "type": "integer", "minimum": 0, "exclusiveMinimum": false }, "rotateSecret": { "type": "boolean", "default": false } }, "required": [ "url", "enabled", "expectedVersion" ] }, "CallbackSavedDto": { "type": "object", "properties": { "url": { "type": "string" }, "enabled": { "type": "boolean" }, "version": { "type": "number" }, "configured": { "type": "boolean" }, "available": { "type": "boolean" }, "updatedAt": { "type": "string", "nullable": true }, "secret": { "type": "string" } }, "required": [ "url", "enabled", "version", "configured", "available", "updatedAt" ] }, "CallbackDeliveryListDto": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "integrationId": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RETRY", "DELIVERED", "DEAD", "CANCELLED" ] }, "attempts": { "type": "number" }, "lastHttpStatus": { "type": "number", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "deliveredAt": { "type": "string", "nullable": true } }, "required": [ "id", "integrationId", "type", "status", "attempts", "lastHttpStatus", "lastError", "createdAt", "deliveredAt" ] } } }, "required": [ "items" ] }, "MeProfileDto": { "type": "object", "properties": { "subject": { "type": "string" }, "username": { "type": "string" }, "email": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "displayName": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string" } }, "tenants": { "type": "array", "items": { "type": "string" } }, "nameEditable": { "type": "boolean" }, "emailEditable": { "type": "boolean" } }, "required": [ "subject", "username", "email", "firstName", "lastName", "displayName", "roles", "tenants", "nameEditable", "emailEditable" ] }, "UpdateMeProfileBodyDto": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 80 }, "lastName": { "type": "string", "maxLength": 80 } }, "required": [ "firstName", "lastName" ] }, "TenantPreferenceDto": { "type": "object", "properties": { "lastTenantId": { "description": "The company the user last switched to, or null when there is none or the user is no longer a member of it. Never a permission: the portal still checks it against the fresh token.", "type": "string", "nullable": true } }, "required": [ "lastTenantId" ] }, "UpdateTenantPreferenceBodyDto": { "type": "object", "properties": { "tenantId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "tenantId" ] } } } }