{ "openapi": "3.1.0", "info": { "title": "AZDAN E-Invoicing — Tenant API", "version": "0.1.0", "description": "Every API an AZDAN tenant can use: the **Tenant Console API** (what the portal does on a signed-in user's behalf) and the **Integration API** (ERP and system-to-system access with an API key), plus sign-in, multi-factor authentication and account activation.\n\nThis reference is generated from the running platform — its routes and validation rules — and checked on every build, so it lists exactly the endpoints that exist, with the request rules the server enforces.\n\n## Environments\n| Environment | Base URL | Peppol network |\n|---|---|---|\n| Development | `https://peppol-dev.azdanapps.com` | Peppol test network |\n| Production | `https://peppol.azdanapps.com` | Peppol production network |\n\nPaths and contracts are identical in both environments. Integration requests choose the Peppol network with `environment` (`test` | `production`).\n\n## Authentication\n**Integration API — API key.** Create a key in the Tenant Console (*API Keys*) and send it as `Authorization: Bearer azd_live_…` or `azd_test_…`. Each operation lists the scopes it accepts in `x-azdan-scopes`; any one of them is enough. Use **Authorize → ApiKeyBearer** to try these operations here.\n\n**Tenant Console API — user session.** `POST /api/auth/login` returns a session token (and sets the `azdan_session` cookie). Send it as `Authorization: Bearer `, or rely on the cookie and add `X-CSRF-Token` (the `azdan_csrf` cookie value) on POST, PUT, PATCH and DELETE. Sessions last 8 hours.\n\n**Multi-factor authentication is mandatory.** An account with MFA signs in in two steps: `POST /api/auth/login` returns `{ mfaRequired: true, ticket }`, and `POST /api/auth/mfa/verify` exchanges the ticket and a 6-digit code for the session. An account without MFA can only set it up (`/api/auth/mfa/status`, `/setup`, `/enable`, `/api/auth/me`) until it is enabled; every other call answers `403 MFA_ENROLLMENT_REQUIRED`.\n\n## Roles\n`tenant_admin` manages the tenant: users, API keys, webhooks, company and participant data, EmaraTax linkage. `tenant_user` works with transactions, documents and reports, limited to the companies and participants assigned to them. Every response is scoped to the caller's own tenant.\n\n## Errors\nErrors share one shape: `{ \"error\": { \"code\", \"message\", \"details?\", \"issues?\" } }`. A request that fails validation answers `400 VALIDATION`, with each failed field in `issues`. Codes are stable and safe to branch on; messages are written to be shown to users.\n\n## Rate limits\nRequests are rate-limited per API key or per client. A limited request answers `429` with `RateLimit-*` and `Retry-After` headers; retry after the indicated time.\n\n## Conventions\nJSON in UTF-8; times in ISO 8601 UTC. Identifiers in the examples are shortened and masked (`txn_8F2K…`, `1004****59`).", "contact": { "name": "AZDAN e-Invoicing support", "email": "peppol@azdan.com" } }, "servers": [ { "url": "https://peppol-dev.azdanapps.com", "description": "Development" }, { "url": "https://peppol.azdanapps.com", "description": "Production" } ], "tags": [ { "name": "Authentication", "description": "Sign-in, session, current principal and multi-factor authentication for both portals." }, { "name": "Account activation", "description": "One-time activation links sent to new users: validate the link, then set a password." }, { "name": "Dashboard & compliance", "description": "Tenant home-screen figures, analytics and the compliance score." }, { "name": "Transactions", "description": "Outbound and inbound Peppol transactions of the signed-in tenant: list, detail (status dimensions, journey, documents), retry of a failed transaction, and the access point's own transaction log." }, { "name": "Documents & files", "description": "Stored files of a transaction (invoice XML/PDF, SBD, TDD, MLS) and short-lived download URLs." }, { "name": "Invoice sending", "description": "Validate and send invoices and credit notes from the portal (session authenticated)." }, { "name": "Reports", "description": "Submission, reconciliation, exception-aging, TDD and VAT reports." }, { "name": "Webhooks", "description": "Webhook endpoints, delivery history, test, replay and signing-secret rotation." }, { "name": "Users & API keys", "description": "Tenant users and integration API keys. Secrets are shown once, on creation." }, { "name": "Company & participants", "description": "Subsidiaries (companies), their Peppol participants and onboarding companies." }, { "name": "Master data", "description": "Customers, items and company profiles used when composing documents." }, { "name": "Mappings", "description": "ERP-to-PINT field mappings: drafts, samples, simulation, activation and rollback." }, { "name": "EmaraTax (FTA)", "description": "Linking, re-verifying and offboarding taxpayers through EmaraTax (UAE FTA)." }, { "name": "Settings & integrations", "description": "Notification settings, tenant preferences, NetSuite connection and the audit log." }, { "name": "Integration API · Peppol", "description": "The public, API-key authenticated Integration API: validate, submit and track Peppol documents. Specified in full by the public Integration API reference (/docs)." }, { "name": "Integration API · Documents", "description": "API-key document downloads for integrations." } ], "x-tagGroups": [ { "name": "Getting started", "tags": [ "Authentication", "Account activation" ] }, { "name": "Tenant Console API (session)", "tags": [ "Dashboard & compliance", "Transactions", "Documents & files", "Invoice sending", "Reports", "Webhooks", "Users & API keys", "Company & participants", "Master data", "Mappings", "EmaraTax (FTA)", "Settings & integrations" ] }, { "name": "Integration API (API key)", "tags": [ "Integration API · Peppol", "Integration API · Documents" ] } ], "paths": { "/api/auth/login": { "post": { "operationId": "postAuthLogin", "summary": "Sign in with email and password", "description": "Step 1 of portal sign-in. Looks the user up by lower-cased email and accepts only `status: active` accounts whose bcrypt hash matches.\n\n- **Portal matrix** — with `portal: \"tenant\"` a `super_admin` is refused, with `portal: \"admin\"` every non-super-admin is refused (`403 WRONG_PORTAL`). Without `portal` no matrix is applied.\n- **Suspended tenant** — after the password matched, a tenant principal whose tenant is not active gets `403 TENANT_SUSPENDED`.\n- **MFA enabled** — no session is issued. The response is `{ mfaRequired: true, ticket, methods }`: `ticket` is an HS256 JWT with audience `azdan-mfa` and `typ: mfa_ticket`, valid `MFA_TICKET_TTL_S` (default 300 s), redeemable only at `POST /api/auth/mfa/verify`; it is never accepted as a session.\n- **MFA not enabled** — `lastLoginAt` is updated, a session JWT is signed (claims `sub`, `role`, `tenantId`, `email`, `tv` token version, `scope` `admin`|`tenant`; expiry `JWT_EXPIRES_IN`, default 8 h), set as the HTTP-only `azdan_session` cookie and returned as `token`.\n- **Mandatory MFA** (`AUTH_MFA_REQUIRED`, default on) — on that branch the response says `mfaEnrollmentRequired: true`: the session can call only `GET /api/auth/me`, `GET /api/auth/mfa/status`, `POST /api/auth/mfa/setup` and `POST /api/auth/mfa/enable`; every other route answers `403 MFA_ENROLLMENT_REQUIRED` until MFA is enabled. The portals send the user straight to MFA setup.\n\nEvery attempt is audited (`auth.login`, success/failure/denied). The readable `azdan_csrf` cookie is **not** set here; it is issued by the first safe (`GET`) request to an `/api/*` route behind the CSRF middleware.\n\n**Rate limit:** per IP, `RATE_LIMIT_LOGIN_MAX` (default 10) per `RATE_LIMIT_LOGIN_WINDOW_MS` (default 60 s), on top of the global `/api` limit. In demo mode (`USE_MOCK_DATA=true`) only built-in demo principals are accepted and none carries MFA.\n\n**Access:** Public — no credentials.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8, "maxLength": 200 }, "captchaId": { "type": "string", "maxLength": 64 }, "captchaAnswer": { "type": "string", "maxLength": 16 }, "portal": { "type": "string", "enum": [ "admin", "tenant" ] } }, "required": [ "email", "password" ] }, "example": { "email": "o***@example.com", "password": "••••••••••••", "portal": "tenant" } } } }, "responses": { "200": { "description": "Signed in (session cookie set), or an MFA challenge when the account has MFA enabled (no cookie). The example is the session form; the challenge form is `{ \"mfaRequired\": true, \"ticket\": \"eyJhbGciOi…\", \"methods\": [\"totp\", \"recovery_code\"] }`.", "headers": { "Set-Cookie": { "description": "`azdan_session=; Path=/; HttpOnly; SameSite=Lax` (+ `Secure` in production). Name, domain, SameSite, Secure and max-age come from `AUTH_COOKIE_*` (max-age default 8 h).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "token", "principal", "mfaEnabled" ], "properties": { "token": { "type": "string", "description": "Session JWT (same value as the cookie)." }, "principal": { "type": "object", "properties": { "sub": { "type": "string" }, "role": { "type": "string", "enum": [ "super_admin", "tenant_admin", "tenant_user" ] }, "tenantId": { "type": [ "string", "null" ] }, "email": { "type": "string" } } }, "mfaEnabled": { "type": "boolean", "description": "Always false on this branch." }, "mfaEnrollmentRequired": { "type": "boolean", "description": "Mandatory MFA: true when this session may only enrol (MFA setup) until MFA is enabled." } } }, { "type": "object", "required": [ "mfaRequired", "ticket", "methods" ], "properties": { "mfaRequired": { "const": true }, "ticket": { "type": "string", "description": "Short-lived MFA ticket for POST /api/auth/mfa/verify." }, "methods": { "type": "array", "items": { "type": "string", "enum": [ "totp", "recovery_code" ] } } } } ] }, "example": { "token": "eyJhbGciOi…", "principal": { "sub": "user_4f1c…", "role": "tenant_admin", "tenantId": "tnt_7Q2X…", "email": "o***@example.com" }, "mfaEnabled": false, "mfaEnrollmentRequired": true } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "description": "Unknown email, wrong password, or the account is not active.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid credentials" } } } } }, "403": { "description": "Wrong portal for this role (`WRONG_PORTAL`), or the tenant is suspended (`TENANT_SUSPENDED`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "WRONG_PORTAL", "message": "Super Admin accounts must sign in via the Admin Portal." } } } } }, "429": { "description": "Rate limit exceeded (login, per IP). Answered by express-rate-limit's default handler: plain-text body `Too many requests, please try again later.` with standard `RateLimit-*` headers.", "content": { "text/plain": { "schema": { "type": "string", "format": "binary" } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [], "x-azdan-access": "public" } }, "/api/auth/mfa/verify": { "post": { "operationId": "postAuthMfaVerify", "summary": "Complete sign-in with an MFA code", "description": "Step 2 of sign-in for MFA-enabled accounts and the only place their session is minted. Verifies the MFA ticket from `POST /api/auth/login` (audience `azdan-mfa`, `typ: mfa_ticket`), re-checks that the user is still active and MFA-enabled and that the tenant is not suspended, then accepts either:\n\n- a 6-digit TOTP code for the active secret, or\n- one of the single-use recovery codes (the matched hash is removed).\n\nOn success `lastLoginAt` is updated, the `azdan_session` cookie is set and the token returned. Each attempt is audited (`auth.mfa.challenge`).\n\n**Rate limit:** per IP, `RATE_LIMIT_MFA_MAX` (default 5) per `RATE_LIMIT_MFA_WINDOW_MS` (default 5 min) — tighter than login, because the code space is 6 digits.\n\n**Access:** Public — no credentials.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket": { "type": "string" }, "code": { "type": "string" } } }, "example": { "ticket": "eyJhbGciOi…", "code": "492817" } } } }, "responses": { "200": { "description": "Signed in. Session cookie set.", "headers": { "Set-Cookie": { "description": "`azdan_session=; Path=/; HttpOnly; SameSite=Lax` (+ `Secure` in production). Name, domain, SameSite, Secure and max-age come from `AUTH_COOKIE_*` (max-age default 8 h).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "principal": { "type": "object", "properties": { "sub": { "type": "string" }, "role": { "type": "string" }, "tenantId": { "type": "string" }, "email": { "type": "string" } } } } }, "example": { "token": "eyJhbGciOi…", "principal": { "sub": "user_4f1c…", "role": "tenant_admin", "tenantId": "tnt_7Q2X…", "email": "o***@example.com" } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "description": "Ticket expired or invalid, MFA not active for the account, account no longer active, or wrong code.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid verification code" } } } } }, "403": { "description": "The tenant was suspended during the ticket's lifetime.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "TENANT_SUSPENDED", "message": "Your organisation's AZDAN account is suspended. Contact AZDAN at sales@azdan.com to request reactivation." } } } } }, "429": { "description": "Rate limit exceeded (MFA verify, per IP). Answered by express-rate-limit's default handler: plain-text body `Too many requests, please try again later.` with standard `RateLimit-*` headers.", "content": { "text/plain": { "schema": { "type": "string", "format": "binary" } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [], "x-azdan-access": "public" } }, "/api/auth/register": { "post": { "operationId": "postAuthRegister", "summary": "create a free AZDAN account (self-registration, Flow A)", "description": "create a free AZDAN account (self-registration, Flow A).\n\nCreates an ACTIVE tenant on the Free plan of the public price list, its administrator\n(invited until the email address is verified) and the Service Agreement receipt, and emails\na single-use 24-hour verification link. The reply is `{ ok: true }` whether or not the\naddress was already known (an existing account is told by email). `website` is a honeypot;\n`captchaToken` is checked when CAPTCHA_SECRET_KEY is set. Rate-limited per IP and globally.\n\n**Access:** Public — no credentials.\n\n**Access:** Public — no credentials.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "minLength": 3, "maxLength": 254 }, "password": { "type": "string", "minLength": 1, "maxLength": 200 }, "displayName": { "type": "string", "minLength": 1, "maxLength": 120 }, "companyName": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "type": "string", "maxLength": 32 }, "locale": { "type": "string", "enum": [ "en", "ar" ] }, "termsAccepted": { "type": "boolean" }, "termsVersion": { "type": "string", "maxLength": 16 }, "website": { "type": "string", "maxLength": 200 }, "captchaToken": { "type": "string", "maxLength": 4096 } }, "required": [ "email", "password", "displayName", "companyName" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [], "x-azdan-access": "public" } }, "/api/auth/register/validate": { "post": { "operationId": "postAuthRegisterValidate", "summary": "the verification page: who is verifying, or why the link cannot be used", "description": "the verification page: who is verifying, or why the link cannot be used.\n\n**Access:** Public — no credentials.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 20, "maxLength": 200 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [], "x-azdan-access": "public" } }, "/api/auth/register/verify": { "post": { "operationId": "postAuthRegisterVerify", "summary": "verify the email address; the link stops working", "description": "verify the email address; the link stops working.\n\n**Access:** Public — no credentials.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 20, "maxLength": 200 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [], "x-azdan-access": "public" } }, "/api/auth/captcha": { "get": { "operationId": "getAuthCaptcha", "summary": "a new image CAPTCHA for a public form that sends email on request", "description": "a new image CAPTCHA for a public form that sends email on request.\n\nReturns `{ captchaId, image, expiresInSeconds }`; `image` is a PNG data URL. The form sends\n`captchaId` and the visitor's `captchaAnswer` back. One attempt per image.\n\n**Access:** Public — no credentials. Rate-limited per IP and globally in app.js.\n\n**Access:** Public — no credentials.", "tags": [ "Authentication" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [], "x-azdan-access": "public" } }, "/api/auth/register/resend": { "post": { "operationId": "postAuthRegisterResend", "summary": "a fresh verification link, at most one a minute", "description": "a fresh verification link, at most one a minute. Needs a\ncorrect image CAPTCHA (`captchaId`, `captchaAnswer`, purpose `resend`).\n\n**Access:** Public — no credentials.", "tags": [ "Authentication" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [], "x-azdan-access": "public" } }, "/api/auth/reactivation-request": { "post": { "operationId": "postAuthReactivationRequest", "summary": "a suspended customer asks AZDAN to reactivate the account (public, rate-limited in app.js)", "description": "a suspended customer asks AZDAN to reactivate the\naccount (public, rate-limited in app.js). Records a lifecycle event and tells sales; the\naccount is NOT reactivated here. The reply is the same for every address. Needs a correct\nimage CAPTCHA (`captchaId`, `captchaAnswer`, purpose `reactivation`).\n\n**Access:** Public — no credentials.", "tags": [ "Authentication" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [], "x-azdan-access": "public" } }, "/api/auth/password-reset/request": { "post": { "operationId": "postAuthPasswordResetRequest", "summary": "email a reset link to a Tenant Console account", "description": "email a reset link to a Tenant Console account.\n\nNeeds a correct image CAPTCHA (`captchaId`, `captchaAnswer`, purpose `password_reset`). The\nreply is `{ ok: true }` for every address, and the email goes out after the reply, so neither\nthe answer nor its timing says whether an account exists.\n\n**Access:** Public — no credentials.\n\n**Access:** Public — no credentials.", "tags": [ "Authentication" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [], "x-azdan-access": "public" } }, "/api/auth/password-reset/validate": { "post": { "operationId": "postAuthPasswordResetValidate", "summary": "the reset page: whose password, or why not", "description": "the reset page: whose password, or why not.\n\n**Access:** Public — no credentials.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 20, "maxLength": 200 } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [], "x-azdan-access": "public" } }, "/api/auth/password-reset/complete": { "post": { "operationId": "postAuthPasswordResetComplete", "summary": "set the new password", "description": "set the new password. The link stops working, every\nsession of the user is revoked and nobody is signed in: MFA applies at the next sign-in.\n\n**Access:** Public — no credentials.", "tags": [ "Authentication" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [], "x-azdan-access": "public" } }, "/api/auth/activation/validate": { "post": { "operationId": "postAuthActivationValidate", "summary": "Check an account activation link", "description": "Called by the activation page before it shows the set-password form. The token from the emailed link (`/portal/activate?token=…`) is hashed (SHA-256) and matched against the user's stored hash; only the hash is ever stored.\n\nValid when the user is still `invited`, the link has not been used and has not expired (`ACTIVATION_TOKEN_TTL_HOURS`, default 72 h). Issuing a new link replaces the hash, so older links stop working. Nothing is changed by this call. `Cache-Control: no-store`.\n\n**Rate limit:** per IP, same budget as login (`RATE_LIMIT_LOGIN_*`, shared prefix `/api/auth/activation`).\n\n**Access:** Public — no credentials.", "tags": [ "Account activation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 20, "maxLength": 200 } }, "required": [ "token" ] }, "example": { "token": "q3Vt9yJx…" } } } }, "responses": { "200": { "description": "The link can be used.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "username": { "type": "string" }, "tenantName": { "type": "string" } } }, "example": { "valid": true, "username": "o***@example.com", "tenantName": "Example Trading LLC" } } } }, "400": { "description": "Unknown token, already used, superseded by a newer link, or the user is no longer `invited`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "ACTIVATION_LINK_INVALID", "message": "This activation link is not valid. It may have been used already, or a newer link was sent." } } } } }, "410": { "description": "The link has expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "ACTIVATION_LINK_EXPIRED", "message": "This activation link has expired. Ask AZDAN (peppol@azdan.com) to send a new one." } } } } }, "429": { "description": "Rate limit exceeded (activation, per IP). Answered by express-rate-limit's default handler: plain-text body `Too many requests, please try again later.` with standard `RateLimit-*` headers.", "content": { "text/plain": { "schema": { "type": "string", "format": "binary" } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [], "x-azdan-access": "public" } }, "/api/auth/activation/complete": { "post": { "operationId": "postAuthActivationComplete", "summary": "Set the password and activate the account", "description": "Re-validates the link exactly like `validate`, then enforces the password policy: at least 12 and at most 200 characters, letters and at least one digit, and not containing the email's local part (when it is 4+ characters). The tenant must be active.\n\nThe password is bcrypt-hashed (cost 12) and the user made `active` in one conditional update on the same token hash and `invited` status, so two parallel submissions activate once; the token is cleared (single use). Side effects: audit `user.activated`; when the user is the tenant's primary administrator, a tenant lifecycle event `admin_activated`. No session is created — the user signs in afterwards. `Cache-Control: no-store`.\n\n**Rate limit:** per IP, same budget as login.\n\n**Access:** Public — no credentials.", "tags": [ "Account activation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "password": { "type": "string" } } }, "example": { "token": "q3Vt9yJx…", "password": "••••••••••••••" } } } }, "responses": { "200": { "description": "Activated. The link no longer works.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "username": { "type": "string" } } }, "example": { "ok": true, "username": "o***@example.com" } } } }, "400": { "description": "Invalid link (`ACTIVATION_LINK_INVALID`) or the password fails the policy (`PASSWORD_POLICY`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "PASSWORD_POLICY", "message": "Use at least 12 characters." } } } } }, "403": { "description": "The tenant is not active.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "TENANT_SUSPENDED", "message": "Your organisation's AZDAN account is suspended. Contact AZDAN at sales@azdan.com to request reactivation." } } } } }, "410": { "description": "The link has expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "ACTIVATION_LINK_EXPIRED", "message": "This activation link has expired. Ask AZDAN (peppol@azdan.com) to send a new one." } } } } }, "429": { "description": "Rate limit exceeded (activation, per IP). Answered by express-rate-limit's default handler: plain-text body `Too many requests, please try again later.` with standard `RateLimit-*` headers.", "content": { "text/plain": { "schema": { "type": "string", "format": "binary" } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [], "x-azdan-access": "public" } }, "/api/auth/logout": { "post": { "operationId": "postAuthLogout", "summary": "Sign out (clear the session cookie)", "description": "Clears the `azdan_session` cookie with the same attributes it was set with and answers `{ ok: true }`. No authentication is required and nothing is checked or stored server-side: the JWT itself is **not** revoked (its `tokenVersion` is not bumped), so a copy of the token stays valid until it expires. The `azdan_csrf` cookie is left in place.\n\n**Access:** Public — no credentials.", "tags": [ "Authentication" ], "responses": { "200": { "description": "Cookie cleared.", "headers": { "Set-Cookie": { "description": "`azdan_session=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT; HttpOnly`", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "example": { "ok": true } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [], "x-azdan-access": "public" } }, "/api/auth/me": { "get": { "operationId": "getAuthMe", "summary": "Get the signed-in principal", "description": "Returns the principal built from the verified session (Bearer JWT or `azdan_session` cookie) after the account, token-version and tenant-suspension checks: `sub`, `role`, `tenantId`, `scope` (`admin` | `tenant`) and `email` — never the token version. For tenant principals it adds `tenant` with the tenant's display name (falling back to the legal name); that lookup is best-effort and its failure never fails the call. `mfa.enrollmentRequired` is true while mandatory MFA still has to be set up — this route stays available then, so the portals can route the user to MFA setup. `preferences.timeZone` is the user's display time zone (an IANA name, `null` = the consoles' default, Asia/Dubai); best-effort, like `tenant`.\n\n**Access:** Any signed-in user (portal session).", "tags": [ "Authentication" ], "responses": { "200": { "description": "The current principal.", "content": { "application/json": { "schema": { "type": "object", "properties": { "principal": { "type": "object", "properties": { "sub": { "type": "string" }, "role": { "type": "string" }, "tenantId": { "type": "string" }, "scope": { "type": "string" }, "email": { "type": "string" } } }, "tenant": { "type": "object", "properties": { "tenantId": { "type": "string" }, "displayName": { "type": "string" } } }, "mfa": { "type": "object", "properties": { "enrollmentRequired": { "type": "boolean" } } }, "preferences": { "type": "object", "properties": { "timeZone": { "type": "string" } } } } }, "example": { "principal": { "sub": "user_4f1c…", "role": "tenant_admin", "tenantId": "tnt_7Q2X…", "scope": "tenant", "email": "o***@example.com" }, "tenant": { "tenantId": "tnt_7Q2X…", "displayName": "Example Trading LLC" }, "mfa": { "enrollmentRequired": false }, "preferences": { "timeZone": "Asia/Dubai" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "session" } }, "/api/auth/me/preferences": { "patch": { "operationId": "patchAuthMePreferences", "summary": "Save the signed-in user's display preferences", "description": "Stores the user's display time zone on the account (`users.preferences.timeZone`): an IANA name such as `Asia/Dubai` or `Europe/London`, or `null` for the consoles' default (Asia/Dubai). It changes only how the consoles show dates — every timestamp is stored and returned in UTC (ISO-8601). Report periods stay in UAE time. In demo mode nothing is stored.\n\n**Access:** Any signed-in user (portal session).", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "timeZone": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 64 } }, "required": [ "timeZone" ], "additionalProperties": false }, "example": { "timeZone": "Europe/London" } } } }, "responses": { "200": { "description": "The saved preferences.", "content": { "application/json": { "schema": { "type": "object", "properties": { "preferences": { "type": "object", "properties": { "timeZone": { "type": "string" } } } } }, "example": { "preferences": { "timeZone": "Europe/London" } } } } }, "400": { "description": "Unknown time zone or extra fields.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request body" } } } } }, "401": { "description": "Not signed in, or the user no longer exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Unknown user" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" }, "503": { "$ref": "#/components/responses/ErrUnavailable" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "session" } }, "/api/auth/me/profile": { "get": { "operationId": "getAuthMeProfile", "summary": "Get the signed-in user's profile", "description": "The user's own name (`displayName`), contact details (`phone`, `jobTitle` — `users.profile`), account facts (e-mail, role, tenant, MFA state, last sign-in, created) and display preferences. Per user; independent of any tenant setting. In demo mode the answer is built from the token alone.\n\n**Access:** Any signed-in user (portal session).", "tags": [ "Authentication" ], "responses": { "200": { "description": "The profile and preferences.", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "phone": { "type": "string" }, "jobTitle": { "type": "string" }, "role": { "type": "string" }, "tenantId": { "type": "string" }, "mfaEnabled": { "type": "boolean" }, "lastLoginAt": { "type": "string" }, "createdAt": { "type": "string" } } }, "preferences": { "type": "object", "properties": { "timeZone": { "type": "string" } } } } }, "example": { "profile": { "userId": "usr_01J9…", "email": "a***@example.com", "displayName": "Amal Haddad", "phone": "+971 4 123 4567", "jobTitle": "Finance lead", "role": "tenant_admin", "tenantId": "tnt_7Q2X…", "mfaEnabled": true, "lastLoginAt": "2026-10-27T08:00:00.000Z", "createdAt": "2026-09-01T08:00:00.000Z" }, "preferences": { "timeZone": "Asia/Dubai" } } } } }, "401": { "description": "Not signed in, or the user no longer exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Unknown user" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" }, "503": { "$ref": "#/components/responses/ErrUnavailable" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "session" }, "patch": { "operationId": "patchAuthMeProfile", "summary": "Edit the signed-in user's profile", "description": "Changes only the fields sent: `displayName` (1–120 characters), `phone` (digits, spaces, brackets and dashes, optional leading `+`; an empty string clears it) and `jobTitle` (up to 80 characters; empty clears it). The e-mail and role cannot be changed here. Audited as `user.profile.update`. In demo mode nothing is stored.\n\n**Access:** Any signed-in user (portal session).", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 120 }, "phone": { "type": "string", "maxLength": 32, "pattern": "^(\\+?[0-9][0-9 ()-]{5,30})?$" }, "jobTitle": { "type": "string", "maxLength": 80 } }, "additionalProperties": false }, "example": { "displayName": "Amal Haddad", "phone": "+971 4 123 4567", "jobTitle": "Finance lead" } } } }, "responses": { "200": { "description": "The saved profile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "userId": { "type": "string" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "phone": { "type": "string" }, "jobTitle": { "type": "string" }, "role": { "type": "string" }, "tenantId": { "type": "string" }, "mfaEnabled": { "type": "boolean" }, "lastLoginAt": { "type": "string" }, "createdAt": { "type": "string" } } } } }, "example": { "profile": { "userId": "usr_01J9…", "email": "a***@example.com", "displayName": "Amal Haddad", "phone": "+971 4 123 4567", "jobTitle": "Finance lead", "role": "tenant_admin", "tenantId": "tnt_7Q2X…", "mfaEnabled": true, "lastLoginAt": "2026-10-27T08:00:00.000Z", "createdAt": "2026-09-01T08:00:00.000Z" } } } } }, "400": { "description": "A field is invalid, unknown, or nothing was sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid request body" } } } } }, "401": { "description": "Not signed in, or the user no longer exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Unknown user" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" }, "503": { "$ref": "#/components/responses/ErrUnavailable" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "session" } }, "/api/auth/me/password": { "post": { "operationId": "postAuthMePassword", "summary": "Change the signed-in user's own password", "description": "Any signed-in user (every tenant role and `super_admin`) changes their own password with `currentPassword`, `newPassword` and the current 6-digit code from their authenticator app (or an unused recovery code) as `code` — or in the `X-Step-Up-Code` header, which the consoles send for critical actions.\n\nChecks, in order: the current password against the bcrypt hash (`400 PASSWORD_INCORRECT`; five wrong passwords in fifteen minutes answer `429 PASSWORD_LOCKED`); the policy of account activation — 12 to 200 characters, not containing the e-mail's local part — plus not equal to the current password (`400 PASSWORD_POLICY`, the message says which rule); then the code, last so a slip does not use one up (verified like a step-up confirmation: single use, five wrong codes lock the user out of step-up for ten minutes — `403 STEP_UP_REQUIRED` / `403 STEP_UP_INVALID` / `429 STEP_UP_LOCKED`, audited as `auth.stepup`).\n\nOn success the new bcrypt hash is stored, `tokenVersion` is bumped so **every other session of the user is signed out**, and a fresh session for this caller is minted: set as the `azdan_session` cookie and returned as `token` (the consoles' proxies store it in their own session cookie, so the browser stays signed in). Audited as `user.password.change` (success and failure, with a reason; never the passwords). Rate-limited per IP like `/mfa/verify` (`RATE_LIMIT_MFA_*`). Refused in demo mode.\n\n**Access:** Any signed-in user (portal session).", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string", "minLength": 1, "maxLength": 200 }, "newPassword": { "type": "string", "minLength": 1, "maxLength": 200 }, "code": { "type": "string", "minLength": 6, "maxLength": 20 } }, "required": [ "currentPassword", "newPassword" ], "additionalProperties": false }, "example": { "currentPassword": "••••••••••••", "newPassword": "••••••••••••••••", "code": "492817" } } } }, "responses": { "200": { "description": "Password changed; other sessions revoked; a fresh session for this caller.", "headers": { "Set-Cookie": { "description": "`azdan_session=; Path=/; HttpOnly; SameSite=Lax` (+ `Secure` in production). Name, domain, SameSite, Secure and max-age come from `AUTH_COOKIE_*` (max-age default 8 h).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "sessionsRevoked": { "type": "boolean" }, "token": { "type": "string" } } }, "example": { "ok": true, "sessionsRevoked": true, "token": "eyJhbGciOi…" } } } }, "400": { "description": "Wrong current password, or the new password breaks the policy (the message says which rule), or demo mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "PASSWORD_INCORRECT", "message": "The current password is incorrect." } } } } }, "401": { "description": "Not signed in, or the user no longer exists or is not active.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Unknown user" } } } } }, "403": { "description": "No code, or a wrong / already-used code.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "STEP_UP_INVALID", "message": "That code is incorrect or has already been used. Enter the current code." } } } } }, "429": { "description": "Five wrong codes (`STEP_UP_LOCKED`, ten minutes) or five wrong passwords (`PASSWORD_LOCKED`, fifteen minutes).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "PASSWORD_LOCKED", "message": "Too many incorrect passwords. Wait a few minutes and try again." } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" }, "503": { "$ref": "#/components/responses/ErrUnavailable" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "session" } }, "/api/auth/mfa/status": { "get": { "operationId": "getAuthMfaStatus", "summary": "Get the MFA state of the signed-in user", "description": "`enabled` — MFA is active; `pending` — `POST /api/auth/mfa/setup` was called but the first code was not yet confirmed; `enrolledAt` — when MFA was enabled; `required` — MFA is mandatory (`AUTH_MFA_REQUIRED`). Available while enrolment is still required. In demo mode the answer is `{ enabled: false, pending: false, supported: false }`.\n\n**Access:** Any signed-in user (portal session).", "tags": [ "Authentication" ], "responses": { "200": { "description": "MFA state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "pending": { "type": "boolean" }, "enrolledAt": { "type": "string" }, "supported": { "type": "boolean" }, "required": { "type": "boolean" } } }, "example": { "enabled": true, "pending": false, "enrolledAt": "2026-09-02T08:14:22.000Z", "supported": true, "required": true } } } }, "401": { "description": "Not signed in, or the user no longer exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Unknown user" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "session" } }, "/api/auth/mfa/setup": { "post": { "operationId": "postAuthMfaSetup", "summary": "Start MFA enrolment (generate a TOTP secret)", "description": "Generates a fresh TOTP secret, stores it encrypted (`MFA_ENCRYPTION_KEY`, falling back to a key derived from the JWT secret) as a **pending** secret — inactive until confirmed with `POST /api/auth/mfa/enable` — and returns it once with the `otpauth://` URL and a server-rendered QR code (SVG data URI). Calling it again replaces the pending secret. The issuer in the QR code is `MFA_ISSUER` (default \"AZDAN ePeppol\"); outside production it names the deployment — \"AZDAN ePeppol (Dev)\", \"AZDAN ePeppol (Staging)\" — so Authenticator entries for different servers are told apart.\n\nRefused when MFA is already enabled (disable first) and in demo mode. Audited as `auth.mfa.setup`; the secret is never logged or audited. No request body.\n\nThis route is mounted before the CSRF middleware, so cookie sessions do not need `X-CSRF-Token` here.\n\n**Access:** Any signed-in user (portal session).", "tags": [ "Authentication" ], "responses": { "200": { "description": "Pending secret created. Show it once, then confirm with /mfa/enable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string" }, "otpauthUrl": { "type": "string" }, "qrCodeDataUri": { "type": "string" }, "issuer": { "type": "string" }, "account": { "type": "string" }, "digits": { "type": "integer" }, "period": { "type": "integer" } } }, "example": { "secret": "JBSWY3DP…", "otpauthUrl": "otpauth://totp/AZDAN%20ePeppol:o***%40example.com?secret=JBSWY3DP…&issuer=AZDAN%20ePeppol&digits=6&period=30", "qrCodeDataUri": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0i…", "issuer": "AZDAN ePeppol", "account": "o***@example.com", "digits": 6, "period": 30 } } } }, "400": { "description": "MFA is already enabled, or demo mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "BAD_REQUEST", "message": "MFA is already enabled. Disable it first to re-enrol." } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "session" } }, "/api/auth/mfa/enable": { "post": { "operationId": "postAuthMfaEnable", "summary": "Confirm the first TOTP code and enable MFA", "description": "Checks `code` against the pending secret from `/mfa/setup`. On success the pending secret becomes the active one, `mfaEnabled` is set with `mfaEnrolledAt`, and 8 recovery codes (`xxxxx-xxxxx`, hex) are generated — stored only as SHA-256 hashes and returned **once**. Audited as `auth.mfa.enable` (success and failure). Sessions already issued stay valid, and the mandatory-MFA enrolment gate lifts on the next request (no new sign-in needed). Mounted before the CSRF middleware.\n\n**Access:** Any signed-in user (portal session).", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } } }, "example": { "code": "492817" } } } }, "responses": { "200": { "description": "MFA enabled. Store the recovery codes now; they are not shown again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "recoveryCodes": { "type": "array", "items": { "type": "string" } } } }, "example": { "enabled": true, "recoveryCodes": [ "3f9a1-c07be", "8d2e4-51a09" ] } } } }, "400": { "description": "Wrong code, MFA already enabled, no pending enrolment (`Start enrolment with /mfa/setup first`), or demo mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "BAD_REQUEST", "message": "That code is incorrect. Check your authenticator and try again." } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "session" } }, "/api/auth/mfa/disable": { "post": { "operationId": "postAuthMfaDisable", "summary": "Disable MFA after re-verifying with a code", "description": "Requires a current 6-digit TOTP code or an unused recovery code (a recovery code used here is consumed). On success the active and pending secrets, the recovery codes and `mfaEnrolledAt` are cleared. With mandatory MFA the user is back to enrolment-only (`403 MFA_ENROLLMENT_REQUIRED` elsewhere) from the next request until MFA is set up again. Audited as `auth.mfa.disable` (success and failure). Mounted before the CSRF middleware.\n\n**Access:** Any signed-in user (portal session).", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" } } }, "example": { "code": "492817" } } } }, "responses": { "200": { "description": "MFA disabled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "example": { "enabled": false } } } }, "400": { "description": "Wrong code, MFA not enabled, or demo mode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "BAD_REQUEST", "message": "Invalid verification code" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "session" } }, "/api/tenant/ap-submit/raw": { "post": { "operationId": "postTenantApSubmitRaw", "summary": "Submit a raw UBL document with Peppol routing headers", "description": "Machine submit for clients that send the document bytes themselves. Despite the name it is not a blind pipe: the body is read into memory (max `AP_SUBMIT_MAX_BYTES`, default 15 MB), bound to the `X-Peppol-*` identities and sent through the same pipeline as `POST /api/integrations/peppol/invoices` (PINT-AE validation → persisted transaction → AP Core). The tenant comes from the API key, never from the request.\n\n**Checks, in order:** `Content-Type` is `application/xml`, `text/xml` or `application/octet-stream`; `Content-Length` present, non-zero and within the limit; `X-Peppol-Sender` is an active outbound/both participant of the tenant in the requested environment (`403 SENDER_NOT_OWNED`); the body is not a pre-built StandardBusinessDocument (`422 PREBUILT_SBD_NOT_SUPPORTED`); receiver, document type, process and a 2-letter C1 country are present; the document type is the PINT-AE Billing Invoice or CreditNote (`400 UNSUPPORTED_DOC_TYPE`), the process `urn:peppol:bis:billing` (`400 UNSUPPORTED_PROFILE`); `X-Peppol-C1-Country` equals the participant's registered C1 country (`400 C1_COUNTRY_MISMATCH`).\n\n**FTA C5 accreditation paths (test environment only):** UAE TaxData sent to the FTA sandbox receiver `0242:000773-100` with the exact TaxData document type and tax-reporting process is forwarded byte-for-byte without PINT validation; with `X-Azdan-Accreditation-Test: FTA-C5-TS07 | FTA-C5-TS08` and `X-Payload-SHA256`, an invoice missing only the Seller name is forwarded between two participants of the same tenant. Every other shape is refused on these paths.\n\n**Result:** `202` with `ok: true` when AP Core accepted the message; `502` with `ok: false` and a sanitized `upstream.report` when AP Core rejected it (the transaction is recorded as failed).\n\n**Scope:** `transactions:submit`. **Rate limit:** `AP_SUBMIT_RATE_PER_MIN` (default 60) per minute per API-key prefix (per IP without a Bearer header), shared with `/api/integrations/peppol/*`. Not CSRF-checked (Bearer only).\n\n**Access:** Tenant API key (`Authorization: Bearer azd_…`).", "tags": [ "Integration API · Peppol" ], "parameters": [ { "name": "X-Peppol-Sender", "in": "header", "required": true, "description": "Sender participant id; an optional `iso6523-actorid-upis::` prefix is stripped.", "schema": { "type": "string", "example": "0235:1004****59" } }, { "name": "X-Peppol-Receiver", "in": "header", "required": true, "description": "Receiver participant id.", "schema": { "type": "string", "example": "0235:1002****17" } }, { "name": "X-Peppol-DocType", "in": "header", "required": true, "description": "Peppol document type identifier.", "schema": { "type": "string", "example": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1" } }, { "name": "X-Peppol-Process", "in": "header", "required": true, "description": "Peppol process identifier.", "schema": { "type": "string", "example": "urn:peppol:bis:billing" } }, { "name": "X-Peppol-C1-Country", "in": "header", "required": true, "description": "ISO 3166-1 alpha-2 country of C1.", "schema": { "type": "string", "example": "AE" } }, { "name": "X-Peppol-Environment", "in": "header", "required": false, "description": "`test` (default) or `production` (`prod`/`live` also mean production; anything else is test).", "schema": { "type": "string", "enum": [ "test", "production" ] } }, { "name": "Content-Length", "in": "header", "required": true, "description": "Body size in bytes; required, > 0 and ≤ `AP_SUBMIT_MAX_BYTES`.", "schema": { "type": "integer" } }, { "name": "X-Azdan-Accreditation-Test", "in": "header", "required": false, "description": "FTA C5 accreditation only: exactly `FTA-C5-TS07` or `FTA-C5-TS08`.", "schema": { "type": "string", "enum": [ "FTA-C5-TS07", "FTA-C5-TS08" ] } }, { "name": "X-Payload-SHA256", "in": "header", "required": false, "description": "Hex SHA-256 of the body; required with `X-Azdan-Accreditation-Test`.", "schema": { "type": "string" } }, { "name": "X-Azdan-Test-Run-Id", "in": "header", "required": false, "description": "Optional C5 evidence label (validated, recorded with the transaction).", "schema": { "type": "string" } }, { "name": "X-Azdan-Test-Scenario", "in": "header", "required": false, "description": "Optional C5 evidence label.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "The raw UBL document bytes (UTF-8). Not JSON.", "content": { "application/xml": { "schema": { "type": "string", "format": "binary" }, "example": "\n…" }, "text/xml": { "schema": { "type": "string", "format": "binary" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "202": { "description": "Validated and accepted by AP Core.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "transactionId": { "type": "string" }, "tenantId": { "type": "string" }, "status": { "type": "string" }, "payloadFormat": { "type": "string" }, "as4MessageId": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "documents": { "type": "object", "properties": { "invoiceXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "string" } } } } }, "upstream": { "type": "object", "properties": { "status": { "type": "integer" } } } } }, "example": { "ok": true, "transactionId": "txn_1789562400000_9f3a…", "tenantId": "tnt_7Q2X…", "status": "sending", "payloadFormat": "raw-ubl", "as4MessageId": "f0debc61-215c-4e0a-9d1b-…@peppol.azdanapps.com", "sbdhInstanceId": "6c1d2e3f-4a5b-…", "documents": { "invoiceXml": { "available": true, "fileId": "file_01J9Z3…", "fileName": "txn_1789562400000_9f3a….xml", "contentType": "application/xml", "downloadUrl": "/api/integrations/peppol/transactions/txn_1789562400000_9f3a…/files/invoice-xml" } }, "upstream": { "status": 200 } } } } }, "400": { "description": "Bad content type, missing/zero/oversized `Content-Length`, missing routing header, unsupported document type or process, C1 mismatch, or PINT-AE validation failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "xpath": { "type": "string" } } } } } } } }, "example": { "error": { "code": "UNSUPPORTED_DOC_TYPE", "message": "X-Peppol-DocType 'urn:…' is not a document type this platform validates and submits. Only the PINT-AE Billing Invoice and CreditNote are accepted.", "details": [ { "code": "UNSUPPORTED_DOC_TYPE", "message": "…", "xpath": "" } ] } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "description": "The sender is not an active outbound participant of this tenant in that environment, or the key lacks `transactions:submit`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "SENDER_NOT_OWNED", "message": "SENDER_NOT_OWNED" } } } } }, "422": { "description": "A pre-built StandardBusinessDocument was sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "xpath": { "type": "string" } } } } } } } }, "example": { "error": { "code": "PREBUILT_SBD_NOT_SUPPORTED", "message": "Pre-built StandardBusinessDocument submissions are not accepted: their routing identities cannot be bound to the validated document. …", "details": [ { "code": "PREBUILT_SBD_NOT_SUPPORTED", "message": "Submit the UBL document without an SBD wrapper.", "xpath": "/" } ] } } } } }, "429": { "description": "Rate limit exceeded (submit, per API key). Answered by express-rate-limit's default handler: plain-text body `Too many requests, please try again later.` with standard `RateLimit-*` headers.", "content": { "text/plain": { "schema": { "type": "string", "format": "binary" } } } }, "500": { "$ref": "#/components/responses/ErrInternal" }, "502": { "description": "AP Core rejected the message. Same shape as 202 with `ok: false`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "transactionId": { "type": "string" }, "tenantId": { "type": "string" }, "status": { "type": "string" }, "payloadFormat": { "type": "string" }, "as4MessageId": { "type": "null" }, "sbdhInstanceId": { "type": "null" }, "upstream": { "type": "object", "properties": { "status": { "type": "integer" }, "report": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "example": { "ok": false, "transactionId": "txn_1789562400000_9f3a…", "tenantId": "tnt_7Q2X…", "status": "failed", "payloadFormat": "raw-ubl", "as4MessageId": null, "sbdhInstanceId": null, "upstream": { "status": 422, "report": { "errors": [ { "code": "PEPPOL-EN16931-R001", "message": "…" } ] } } } } } } }, "security": [ { "ApiKeyBearer": [] } ], "x-azdan-access": "apiKey" } }, "/api/integrations/peppol/validate": { "post": { "operationId": "validateDocument", "summary": "Validate a Peppol document", "description": "Dry-run validation. Checks your document against PINT/BIS Schematron\nrules without creating a transaction or contacting the Peppol network.\nSafe to call repeatedly during development.\n\n\n**Access:** Tenant API key (`Authorization: Bearer azd_…`).\n\n**API-key scopes (any one):** `peppol:validate`, `peppol:submit`, `transactions:submit`, `transactions:read`", "tags": [ "Integration API · Peppol" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateRequest" }, "examples": { "jsonMode": { "summary": "JSON mode — Minimal Tax Invoice (380)", "description": "The smallest request the API accepts for a UAE tax invoice. Start here and add only what your business case needs.", "value": { "inputType": "json", "environment": "test", "documentType": "invoice", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "payload": { "invoiceKind": "tax", "invoiceNumber": "INV-2026-000123", "uniqueIdentifierNumber": "3f2504e0-4f89-41d3-9a0c-000000000005", "issueDate": "2026-09-16", "dueDate": "2026-10-16", "currency": "AED", "transactionTypeCode": "00000000", "paymentMeansCode": "30", "paymentAccountId": "AE070331234567890123456", "supplier": { "name": "AZDAN Sample Supplier LLC", "schemeId": "0235", "peppolId": "1000000001", "taxId": "100000000000103", "legalRegistrationId": "CN-1234567", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development Dubai", "address": { "streetName": "Sheikh Zayed Road 12", "cityName": "Dubai", "countrySubentity": "DXB", "countryCode": "AE" } }, "customer": { "name": "Emirates Buyer Trading LLC", "schemeId": "0235", "peppolId": "1000000002", "taxId": "100000000000203", "address": { "streetName": "Corniche Road 88", "cityName": "Abu Dhabi", "countrySubentity": "AUH", "countryCode": "AE" } }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00" }, "item": { "name": "Consulting services", "description": "Professional services for September 2026" }, "tax": { "category": "S", "rate": "5" } } ], "taxTotal": { "taxAmount": "50.00", "taxSubtotals": [ { "category": "S", "percent": "5.00", "taxableAmount": "1000.00", "taxAmount": "50.00" } ] }, "legalMonetaryTotal": { "lineExtensionAmount": "1000.00", "taxExclusiveAmount": "1000.00", "taxInclusiveAmount": "1050.00", "payableAmount": "1050.00" } } } }, "xmlMode": { "summary": "XML mode — UAE Tax Invoice (380)", "description": "The standard VAT invoice. Carries all 51 MoF mandatory Tax Invoice fields. The xml value is the UBL 2.1 document the API builds for the JSON example of the same name; it passes PINT-AE 1.0.4.", "value": { "inputType": "xml", "environment": "test", "documentType": "invoice", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "xml": "\n\n urn:peppol:pint:billing-1@ae-1\n urn:peppol:bis:billing\n 00000000\n INV-2026-000123\n 3f2504e0-4f89-41d3-9a0c-000000000001\n 2026-09-16\n 2026-10-16\n 380\n Thank you for your business.\n AED\n \n \n 1000000001\n AZDAN Sample Supplier LLC\n \n Sheikh Zayed Road 12\n Office 401\n Dubai\n 00000\n DXB\n AE\n \n \n 100000000000103\n VAT\n \n \n AZDAN Sample Supplier LLC\n CN-1234567\n \n \n \n \n 1000000002\n Emirates Buyer Trading LLC\n \n Corniche Road 88\n Abu Dhabi\n 11111\n AUH\n AE\n \n \n 100000000000203\n VAT\n \n \n Emirates Buyer Trading LLC\n \n \n \n 30\n AE070331234567890123456\n \n \n Net 30 days\n \n \n 50.00\n \n 1000.00\n 50.00\n \n S\n 5.00\n VAT\n \n \n \n \n 1000.00\n 1000.00\n 1050.00\n 1050.00\n \n \n 1\n 10\n 1000.00\n \n Professional services for September 2026\n Consulting services\n \n S\n 5.00\n VAT\n \n \n \n 100.00\n 1\n \n false\n 20.00\n 120.00\n \n \n \n 1000.00\n \n 50.00\n \n \n \n" } }, "creditNoteJsonMode": { "summary": "JSON mode — UAE Tax Credit Note (381) (381)", "description": "Reverses a tax invoice. Amounts stay POSITIVE; the document type says it is a credit. Needs a reason code and the original invoice reference.", "value": { "inputType": "json", "environment": "test", "documentType": "creditNote", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "payload": { "invoiceKind": "tax", "invoiceNumber": "CN-2026-000123", "uniqueIdentifierNumber": "3f2504e0-4f89-41d3-9a0c-000000000002", "issueDate": "2026-09-16", "currency": "AED", "transactionTypeCode": "00000000", "note": "Credit for returned services.", "creditNoteReasonCode": "DL8.61.1.D", "billingReference": { "invoiceId": "INV-2026-000123", "issueDate": "2026-09-16" }, "supplier": { "name": "AZDAN Sample Supplier LLC", "schemeId": "0235", "peppolId": "1000000001", "taxId": "100000000000103", "legalRegistrationId": "CN-1234567", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development Dubai", "address": { "streetName": "Sheikh Zayed Road 12", "additionalStreetName": "Office 401", "cityName": "Dubai", "postalZone": "00000", "countrySubentity": "DXB", "countryCode": "AE" } }, "customer": { "name": "Emirates Buyer Trading LLC", "schemeId": "0235", "peppolId": "1000000002", "taxId": "100000000000203", "address": { "streetName": "Corniche Road 88", "cityName": "Abu Dhabi", "postalZone": "11111", "countrySubentity": "AUH", "countryCode": "AE" } }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00" }, "item": { "name": "Consulting services", "description": "Professional services for September 2026" }, "tax": { "category": "S", "rate": "5" } } ], "taxTotal": { "taxAmount": "50.00", "taxSubtotals": [ { "category": "S", "percent": "5.00", "taxableAmount": "1000.00", "taxAmount": "50.00" } ] }, "legalMonetaryTotal": { "lineExtensionAmount": "1000.00", "taxExclusiveAmount": "1000.00", "taxInclusiveAmount": "1050.00", "payableAmount": "1050.00" } } } }, "creditNoteXmlMode": { "summary": "XML mode — UAE Tax Credit Note (381)", "description": "Reverses a tax invoice. Amounts stay POSITIVE; the document type says it is a credit. Needs a reason code and the original invoice reference. The xml value is the UBL 2.1 document the API builds for the JSON example of the same name; it passes PINT-AE 1.0.4.", "value": { "inputType": "xml", "environment": "test", "documentType": "creditNote", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "xml": "\n\n urn:peppol:pint:billing-1@ae-1\n urn:peppol:bis:billing\n 00000000\n CN-2026-000123\n 3f2504e0-4f89-41d3-9a0c-000000000002\n 2026-09-16\n 381\n Credit for returned services.\n AED\n \n DL8.61.1.D\n \n \n \n INV-2026-000123\n 2026-09-16\n \n \n \n \n 1000000001\n AZDAN Sample Supplier LLC\n \n Sheikh Zayed Road 12\n Office 401\n Dubai\n 00000\n DXB\n AE\n \n \n 100000000000103\n VAT\n \n \n AZDAN Sample Supplier LLC\n CN-1234567\n \n \n \n \n 1000000002\n Emirates Buyer Trading LLC\n \n Corniche Road 88\n Abu Dhabi\n 11111\n AUH\n AE\n \n \n 100000000000203\n VAT\n \n \n Emirates Buyer Trading LLC\n \n \n \n 50.00\n \n 1000.00\n 50.00\n \n S\n 5.00\n VAT\n \n \n \n \n 1000.00\n 1000.00\n 1050.00\n 1050.00\n \n \n 1\n 10\n 1000.00\n \n Professional services for September 2026\n Consulting services\n \n S\n 5.00\n VAT\n \n \n \n 100.00\n 1\n \n false\n 0.00\n 100.00\n \n \n \n 1000.00\n \n 50.00\n \n \n \n" } }, "commercialInvoiceJsonMode": { "summary": "JSON mode — UAE Commercial Invoice (480) (480)", "description": "Issued when no VAT is charged. Carries all 49 MoF mandatory Commercial Invoice fields: the seller states its TIN instead of a VAT TRN, the buyer its legal registration, and every tax category is E, O or Z.", "value": { "inputType": "json", "environment": "test", "documentType": "invoice", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "payload": { "invoiceKind": "commercial", "invoiceNumber": "CINV-2026-000123", "uniqueIdentifierNumber": "3f2504e0-4f89-41d3-9a0c-000000000003", "issueDate": "2026-09-16", "dueDate": "2026-10-16", "currency": "AED", "transactionTypeCode": "00000000", "note": "Thank you for your business.", "paymentMeansCode": "30", "paymentAccountId": "AE070331234567890123456", "paymentTerms": { "note": "Net 30 days" }, "supplier": { "name": "AZDAN Sample Supplier LLC", "schemeId": "0235", "peppolId": "1000000001", "taxRegistrationId": "1000000001", "taxSchemeId": "TIN", "legalRegistrationId": "CN-1234567", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development Dubai", "address": { "streetName": "Sheikh Zayed Road 12", "additionalStreetName": "Office 401", "cityName": "Dubai", "postalZone": "00000", "countrySubentity": "DXB", "countryCode": "AE" } }, "customer": { "name": "Emirates Buyer Trading LLC", "schemeId": "0235", "peppolId": "1000000002", "legalRegistrationId": "CN-7654321", "legalRegistrationType": "CL", "legalRegistrationAuthorityName": "Abu Dhabi Department of Economic Development", "address": { "streetName": "Corniche Road 88", "cityName": "Abu Dhabi", "postalZone": "11111", "countrySubentity": "AUH", "countryCode": "AE" } }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00", "grossPriceAmount": "120.00", "baseQuantity": "1" }, "item": { "name": "Consulting services", "description": "Professional services for September 2026" }, "tax": { "category": "Z", "rate": "0" } } ], "taxTotal": { "taxAmount": "0.00", "taxSubtotals": [ { "category": "Z", "percent": "0.00", "taxableAmount": "1000.00", "taxAmount": "0.00" } ] }, "legalMonetaryTotal": { "lineExtensionAmount": "1000.00", "taxExclusiveAmount": "1000.00", "taxInclusiveAmount": "1000.00", "payableAmount": "1000.00" } } } }, "commercialInvoiceXmlMode": { "summary": "XML mode — UAE Commercial Invoice (480)", "description": "Issued when no VAT is charged. Carries all 49 MoF mandatory Commercial Invoice fields: the seller states its TIN instead of a VAT TRN, the buyer its legal registration, and every tax category is E, O or Z. The xml value is the UBL 2.1 document the API builds for the JSON example of the same name; it passes PINT-AE 1.0.4.", "value": { "inputType": "xml", "environment": "test", "documentType": "invoice", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "xml": "\n\n urn:peppol:pint:billing-1@ae-1\n urn:peppol:bis:billing\n 00000000\n CINV-2026-000123\n 3f2504e0-4f89-41d3-9a0c-000000000003\n 2026-09-16\n 2026-10-16\n 480\n Thank you for your business.\n AED\n \n \n 1000000001\n AZDAN Sample Supplier LLC\n \n Sheikh Zayed Road 12\n Office 401\n Dubai\n 00000\n DXB\n AE\n \n \n 1000000001\n TIN\n \n \n AZDAN Sample Supplier LLC\n CN-1234567\n \n \n \n \n 1000000002\n Emirates Buyer Trading LLC\n \n Corniche Road 88\n Abu Dhabi\n 11111\n AUH\n AE\n \n \n Emirates Buyer Trading LLC\n CN-7654321\n \n \n \n 30\n AE070331234567890123456\n \n \n Net 30 days\n \n \n 0.00\n \n 1000.00\n 0.00\n \n Z\n 0.00\n VAT\n \n \n \n \n 1000.00\n 1000.00\n 1000.00\n 1000.00\n \n \n 1\n 10\n 1000.00\n \n Professional services for September 2026\n Consulting services\n \n Z\n 0.00\n VAT\n \n \n \n 100.00\n 1\n \n false\n 20.00\n 120.00\n \n \n \n 1000.00\n \n 0.00\n \n \n \n" } }, "commercialCreditNoteJsonMode": { "summary": "JSON mode — UAE Commercial Credit Note (81) (81)", "description": "Reverses a commercial invoice. Same identity rules as 480.", "value": { "inputType": "json", "environment": "test", "documentType": "creditNote", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "payload": { "invoiceKind": "commercial", "invoiceNumber": "CCN-2026-000123", "uniqueIdentifierNumber": "3f2504e0-4f89-41d3-9a0c-000000000004", "issueDate": "2026-09-16", "currency": "AED", "transactionTypeCode": "00000000", "note": "Credit for returned goods.", "creditNoteReasonCode": "DL8.61.1.D", "billingReference": { "invoiceId": "CINV-2026-000123", "issueDate": "2026-09-16" }, "supplier": { "name": "AZDAN Sample Supplier LLC", "schemeId": "0235", "peppolId": "1000000001", "taxRegistrationId": "1000000001", "taxSchemeId": "TIN", "legalRegistrationId": "CN-1234567", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development Dubai", "address": { "streetName": "Sheikh Zayed Road 12", "additionalStreetName": "Office 401", "cityName": "Dubai", "postalZone": "00000", "countrySubentity": "DXB", "countryCode": "AE" } }, "customer": { "name": "Emirates Buyer Trading LLC", "schemeId": "0235", "peppolId": "1000000002", "legalRegistrationId": "CN-7654321", "legalRegistrationType": "CL", "legalRegistrationAuthorityName": "Abu Dhabi Department of Economic Development", "address": { "streetName": "Corniche Road 88", "cityName": "Abu Dhabi", "postalZone": "11111", "countrySubentity": "AUH", "countryCode": "AE" } }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00" }, "item": { "name": "Consulting services", "description": "Professional services for September 2026" }, "tax": { "category": "Z", "rate": "0" } } ], "taxTotal": { "taxAmount": "0.00", "taxSubtotals": [ { "category": "Z", "percent": "0.00", "taxableAmount": "1000.00", "taxAmount": "0.00" } ] }, "legalMonetaryTotal": { "lineExtensionAmount": "1000.00", "taxExclusiveAmount": "1000.00", "taxInclusiveAmount": "1000.00", "payableAmount": "1000.00" } } } }, "commercialCreditNoteXmlMode": { "summary": "XML mode — UAE Commercial Credit Note (81)", "description": "Reverses a commercial invoice. Same identity rules as 480. The xml value is the UBL 2.1 document the API builds for the JSON example of the same name; it passes PINT-AE 1.0.4.", "value": { "inputType": "xml", "environment": "test", "documentType": "creditNote", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "xml": "\n\n urn:peppol:pint:billing-1@ae-1\n urn:peppol:bis:billing\n 00000000\n CCN-2026-000123\n 3f2504e0-4f89-41d3-9a0c-000000000004\n 2026-09-16\n 81\n Credit for returned goods.\n AED\n \n DL8.61.1.D\n \n \n \n CINV-2026-000123\n 2026-09-16\n \n \n \n \n 1000000001\n AZDAN Sample Supplier LLC\n \n Sheikh Zayed Road 12\n Office 401\n Dubai\n 00000\n DXB\n AE\n \n \n 1000000001\n TIN\n \n \n AZDAN Sample Supplier LLC\n CN-1234567\n \n \n \n \n 1000000002\n Emirates Buyer Trading LLC\n \n Corniche Road 88\n Abu Dhabi\n 11111\n AUH\n AE\n \n \n Emirates Buyer Trading LLC\n CN-7654321\n \n \n \n 0.00\n \n 1000.00\n 0.00\n \n Z\n 0.00\n VAT\n \n \n \n \n 1000.00\n 1000.00\n 1000.00\n 1000.00\n \n \n 1\n 10\n 1000.00\n \n Professional services for September 2026\n Consulting services\n \n Z\n 0.00\n VAT\n \n \n \n 100.00\n 1\n \n false\n 0.00\n 100.00\n \n \n \n 1000.00\n \n 0.00\n \n \n \n" } }, "uaeScenarioJsonMode": { "summary": "JSON mode — Combined scenarios (380)", "description": "Positions 1, 4, 6 and 8 declared together (mask 10010101): the free-zone beneficiary (BTAE-01), the invoice period (IBG-14), the disclosed-agent principal (BTAE-14) and a deliver-to address abroad (IBG-13). Scenarios combine, and each companion element stays mandatory under its own rule — none is derived from a value the invoice already carries.", "value": { "inputType": "json", "environment": "test", "documentType": "invoice", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "payload": { "invoiceKind": "tax", "invoiceNumber": "INV-2026-000123", "uniqueIdentifierNumber": "3f2504e0-4f89-41d3-9a0c-000000000018", "issueDate": "2026-09-16", "dueDate": "2026-10-16", "currency": "AED", "transactionType": { "freeTradeZone": true, "summaryInvoice": true, "disclosedAgentBilling": true, "export": true }, "invoicePeriod": { "startDate": "2026-09-01", "endDate": "2026-09-30", "frequencyCode": "MTH" }, "paymentMeansCode": "30", "paymentAccountId": "AE070331234567890123456", "supplier": { "name": "AZDAN Sample Supplier LLC", "schemeId": "0235", "peppolId": "1000000001", "taxId": "100000000000103", "legalRegistrationId": "CN-1234567", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development Dubai", "address": { "streetName": "Sheikh Zayed Road 12", "additionalStreetName": "Office 401", "cityName": "Dubai", "postalZone": "00000", "countrySubentity": "DXB", "countryCode": "AE" } }, "customer": { "name": "Emirates Buyer Trading LLC", "schemeId": "0235", "peppolId": "1000000002", "taxId": "100000000000203", "address": { "streetName": "Corniche Road 88", "cityName": "Abu Dhabi", "postalZone": "11111", "countrySubentity": "AUH", "countryCode": "AE" }, "beneficiaryId": "FZ-BEN-778901" }, "agent": { "principalId": "PRINCIPAL-4471" }, "delivery": { "date": "2026-09-25", "address": { "streetName": "Hamngatan 4", "additionalStreetName": "Warehouse B", "cityName": "Goteborg", "postalZone": "41106", "countrySubentity": "Vastra Gotaland", "countryCode": "SE" } }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00" }, "item": { "name": "Consulting services", "description": "Professional services for September 2026" }, "tax": { "category": "S", "rate": "5" } } ], "taxTotal": { "taxAmount": "50.00", "taxSubtotals": [ { "category": "S", "percent": "5.00", "taxableAmount": "1000.00", "taxAmount": "50.00" } ] }, "legalMonetaryTotal": { "lineExtensionAmount": "1000.00", "taxExclusiveAmount": "1000.00", "taxInclusiveAmount": "1050.00", "payableAmount": "1050.00" } } } }, "exemptionReasonJsonMode": { "summary": "JSON mode — Mixed VAT categories (380)", "description": "Standard rated (S), zero rated (Z) and exempt (E) lines on one invoice. The VAT breakdown has one entry per category; the exempt line carries a VAT exemption reason code and no rate.", "value": { "inputType": "json", "environment": "test", "documentType": "invoice", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "payload": { "invoiceKind": "tax", "invoiceNumber": "INV-2026-000123", "uniqueIdentifierNumber": "3f2504e0-4f89-41d3-9a0c-000000000017", "issueDate": "2026-09-16", "dueDate": "2026-10-16", "currency": "AED", "transactionTypeCode": "00000000", "paymentMeansCode": "30", "paymentAccountId": "AE070331234567890123456", "supplier": { "name": "AZDAN Sample Supplier LLC", "schemeId": "0235", "peppolId": "1000000001", "taxId": "100000000000103", "legalRegistrationId": "CN-1234567", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development Dubai", "address": { "streetName": "Sheikh Zayed Road 12", "additionalStreetName": "Office 401", "cityName": "Dubai", "postalZone": "00000", "countrySubentity": "DXB", "countryCode": "AE" } }, "customer": { "name": "Emirates Buyer Trading LLC", "schemeId": "0235", "peppolId": "1000000002", "taxId": "100000000000203", "address": { "streetName": "Corniche Road 88", "cityName": "Abu Dhabi", "postalZone": "11111", "countrySubentity": "AUH", "countryCode": "AE" } }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00" }, "item": { "name": "Consulting services", "description": "Professional services for September 2026" }, "tax": { "category": "S", "rate": "5" } }, { "id": "2", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00" }, "item": { "name": "International freight", "description": "Zero-rated international transport of goods" }, "tax": { "category": "Z", "rate": "0" } }, { "id": "3", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00" }, "item": { "name": "Financial service fee", "description": "Exempt financial service" }, "tax": { "category": "E", "exemptionReasonCode": "VATEX-AE-EXEMPT-FINANCIAL" } } ], "taxTotal": { "taxAmount": "50.00", "taxSubtotals": [ { "category": "S", "percent": "5.00", "taxableAmount": "1000.00", "taxAmount": "50.00" }, { "category": "Z", "percent": "0.00", "taxableAmount": "1000.00", "taxAmount": "0.00" }, { "category": "E", "taxableAmount": "1000.00", "taxAmount": "0.00" } ] }, "legalMonetaryTotal": { "lineExtensionAmount": "3000.00", "taxExclusiveAmount": "3000.00", "taxInclusiveAmount": "3050.00", "payableAmount": "3050.00" } } } } } } } }, "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateResponse" }, "examples": { "valid": { "summary": "Valid document", "value": { "valid": true, "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "warnings": [], "phormSkipped": false, "normalized": { "sender": "0235:1000000001", "receiver": "0235:1000000002", "invoiceNumber": "INV-2026-000123", "issueDate": "2026-09-16", "currency": "AED", "payableAmount": 1050, "invoiceTypeCode": "380", "dueDate": "2026-10-16", "supplierName": "AZDAN Sample Supplier LLC", "customerName": "Emirates Buyer Trading LLC", "netAmount": 1000, "taxAmount": 50 } } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ApiKeyBearer": [] } ], "x-azdan-access": "apiKey", "x-azdan-scopes": [ "peppol:validate", "peppol:submit", "transactions:submit", "transactions:read" ] } }, "/api/integrations/peppol/invoices": { "post": { "operationId": "submitInvoice", "summary": "Submit a Peppol invoice or credit note", "description": "Submit a document for Peppol delivery. Validates, creates a transaction,\nand hands off to the access point for AS4 delivery.\n\nReturns **202 Accepted** — delivery is asynchronous. Subscribe to webhooks\nfor real-time status updates.\n\nSend `Idempotency-Key` as an HTTP header. The key must uniquely identify\none logical submission. Reuse the same key only when retrying the exact\nsame request. Use a new key for a new invoice or credit note.\n\nThe header is authoritative. The legacy request-body field\n`idempotencyKey` is deprecated and supported only for backward\ncompatibility; if both are present they must match.\n\n\n**Access:** Tenant API key (`Authorization: Bearer azd_…`).\n\n**API-key scopes (any one):** `peppol:submit`, `transactions:submit`", "tags": [ "Integration API · Peppol" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitRequest" }, "examples": { "jsonMode": { "summary": "JSON mode — Minimal Tax Invoice (380)", "description": "The smallest request the API accepts for a UAE tax invoice. Start here and add only what your business case needs.", "value": { "inputType": "json", "environment": "test", "documentType": "invoice", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "payload": { "invoiceKind": "tax", "invoiceNumber": "INV-2026-000123", "uniqueIdentifierNumber": "3f2504e0-4f89-41d3-9a0c-000000000005", "issueDate": "2026-09-16", "dueDate": "2026-10-16", "currency": "AED", "transactionTypeCode": "00000000", "paymentMeansCode": "30", "paymentAccountId": "AE070331234567890123456", "supplier": { "name": "AZDAN Sample Supplier LLC", "schemeId": "0235", "peppolId": "1000000001", "taxId": "100000000000103", "legalRegistrationId": "CN-1234567", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development Dubai", "address": { "streetName": "Sheikh Zayed Road 12", "cityName": "Dubai", "countrySubentity": "DXB", "countryCode": "AE" } }, "customer": { "name": "Emirates Buyer Trading LLC", "schemeId": "0235", "peppolId": "1000000002", "taxId": "100000000000203", "address": { "streetName": "Corniche Road 88", "cityName": "Abu Dhabi", "countrySubentity": "AUH", "countryCode": "AE" } }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00" }, "item": { "name": "Consulting services", "description": "Professional services for September 2026" }, "tax": { "category": "S", "rate": "5" } } ], "taxTotal": { "taxAmount": "50.00", "taxSubtotals": [ { "category": "S", "percent": "5.00", "taxableAmount": "1000.00", "taxAmount": "50.00" } ] }, "legalMonetaryTotal": { "lineExtensionAmount": "1000.00", "taxExclusiveAmount": "1000.00", "taxInclusiveAmount": "1050.00", "payableAmount": "1050.00" } } } }, "xmlMode": { "summary": "XML mode — UAE Tax Invoice (380)", "description": "The standard VAT invoice. Carries all 51 MoF mandatory Tax Invoice fields. The xml value is the UBL 2.1 document the API builds for the JSON example of the same name; it passes PINT-AE 1.0.4.", "value": { "inputType": "xml", "environment": "test", "documentType": "invoice", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "xml": "\n\n urn:peppol:pint:billing-1@ae-1\n urn:peppol:bis:billing\n 00000000\n INV-2026-000123\n 3f2504e0-4f89-41d3-9a0c-000000000001\n 2026-09-16\n 2026-10-16\n 380\n Thank you for your business.\n AED\n \n \n 1000000001\n AZDAN Sample Supplier LLC\n \n Sheikh Zayed Road 12\n Office 401\n Dubai\n 00000\n DXB\n AE\n \n \n 100000000000103\n VAT\n \n \n AZDAN Sample Supplier LLC\n CN-1234567\n \n \n \n \n 1000000002\n Emirates Buyer Trading LLC\n \n Corniche Road 88\n Abu Dhabi\n 11111\n AUH\n AE\n \n \n 100000000000203\n VAT\n \n \n Emirates Buyer Trading LLC\n \n \n \n 30\n AE070331234567890123456\n \n \n Net 30 days\n \n \n 50.00\n \n 1000.00\n 50.00\n \n S\n 5.00\n VAT\n \n \n \n \n 1000.00\n 1000.00\n 1050.00\n 1050.00\n \n \n 1\n 10\n 1000.00\n \n Professional services for September 2026\n Consulting services\n \n S\n 5.00\n VAT\n \n \n \n 100.00\n 1\n \n false\n 20.00\n 120.00\n \n \n \n 1000.00\n \n 50.00\n \n \n \n" } }, "creditNoteJsonMode": { "summary": "JSON mode — UAE Tax Credit Note (381) (381)", "description": "Reverses a tax invoice. Amounts stay POSITIVE; the document type says it is a credit. Needs a reason code and the original invoice reference.", "value": { "inputType": "json", "environment": "test", "documentType": "creditNote", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "payload": { "invoiceKind": "tax", "invoiceNumber": "CN-2026-000123", "uniqueIdentifierNumber": "3f2504e0-4f89-41d3-9a0c-000000000002", "issueDate": "2026-09-16", "currency": "AED", "transactionTypeCode": "00000000", "note": "Credit for returned services.", "creditNoteReasonCode": "DL8.61.1.D", "billingReference": { "invoiceId": "INV-2026-000123", "issueDate": "2026-09-16" }, "supplier": { "name": "AZDAN Sample Supplier LLC", "schemeId": "0235", "peppolId": "1000000001", "taxId": "100000000000103", "legalRegistrationId": "CN-1234567", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development Dubai", "address": { "streetName": "Sheikh Zayed Road 12", "additionalStreetName": "Office 401", "cityName": "Dubai", "postalZone": "00000", "countrySubentity": "DXB", "countryCode": "AE" } }, "customer": { "name": "Emirates Buyer Trading LLC", "schemeId": "0235", "peppolId": "1000000002", "taxId": "100000000000203", "address": { "streetName": "Corniche Road 88", "cityName": "Abu Dhabi", "postalZone": "11111", "countrySubentity": "AUH", "countryCode": "AE" } }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00" }, "item": { "name": "Consulting services", "description": "Professional services for September 2026" }, "tax": { "category": "S", "rate": "5" } } ], "taxTotal": { "taxAmount": "50.00", "taxSubtotals": [ { "category": "S", "percent": "5.00", "taxableAmount": "1000.00", "taxAmount": "50.00" } ] }, "legalMonetaryTotal": { "lineExtensionAmount": "1000.00", "taxExclusiveAmount": "1000.00", "taxInclusiveAmount": "1050.00", "payableAmount": "1050.00" } } } }, "creditNoteXmlMode": { "summary": "XML mode — UAE Tax Credit Note (381)", "description": "Reverses a tax invoice. Amounts stay POSITIVE; the document type says it is a credit. Needs a reason code and the original invoice reference. The xml value is the UBL 2.1 document the API builds for the JSON example of the same name; it passes PINT-AE 1.0.4.", "value": { "inputType": "xml", "environment": "test", "documentType": "creditNote", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "xml": "\n\n urn:peppol:pint:billing-1@ae-1\n urn:peppol:bis:billing\n 00000000\n CN-2026-000123\n 3f2504e0-4f89-41d3-9a0c-000000000002\n 2026-09-16\n 381\n Credit for returned services.\n AED\n \n DL8.61.1.D\n \n \n \n INV-2026-000123\n 2026-09-16\n \n \n \n \n 1000000001\n AZDAN Sample Supplier LLC\n \n Sheikh Zayed Road 12\n Office 401\n Dubai\n 00000\n DXB\n AE\n \n \n 100000000000103\n VAT\n \n \n AZDAN Sample Supplier LLC\n CN-1234567\n \n \n \n \n 1000000002\n Emirates Buyer Trading LLC\n \n Corniche Road 88\n Abu Dhabi\n 11111\n AUH\n AE\n \n \n 100000000000203\n VAT\n \n \n Emirates Buyer Trading LLC\n \n \n \n 50.00\n \n 1000.00\n 50.00\n \n S\n 5.00\n VAT\n \n \n \n \n 1000.00\n 1000.00\n 1050.00\n 1050.00\n \n \n 1\n 10\n 1000.00\n \n Professional services for September 2026\n Consulting services\n \n S\n 5.00\n VAT\n \n \n \n 100.00\n 1\n \n false\n 0.00\n 100.00\n \n \n \n 1000.00\n \n 50.00\n \n \n \n" } }, "commercialInvoiceJsonMode": { "summary": "JSON mode — UAE Commercial Invoice (480) (480)", "description": "Issued when no VAT is charged. Carries all 49 MoF mandatory Commercial Invoice fields: the seller states its TIN instead of a VAT TRN, the buyer its legal registration, and every tax category is E, O or Z.", "value": { "inputType": "json", "environment": "test", "documentType": "invoice", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "payload": { "invoiceKind": "commercial", "invoiceNumber": "CINV-2026-000123", "uniqueIdentifierNumber": "3f2504e0-4f89-41d3-9a0c-000000000003", "issueDate": "2026-09-16", "dueDate": "2026-10-16", "currency": "AED", "transactionTypeCode": "00000000", "note": "Thank you for your business.", "paymentMeansCode": "30", "paymentAccountId": "AE070331234567890123456", "paymentTerms": { "note": "Net 30 days" }, "supplier": { "name": "AZDAN Sample Supplier LLC", "schemeId": "0235", "peppolId": "1000000001", "taxRegistrationId": "1000000001", "taxSchemeId": "TIN", "legalRegistrationId": "CN-1234567", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development Dubai", "address": { "streetName": "Sheikh Zayed Road 12", "additionalStreetName": "Office 401", "cityName": "Dubai", "postalZone": "00000", "countrySubentity": "DXB", "countryCode": "AE" } }, "customer": { "name": "Emirates Buyer Trading LLC", "schemeId": "0235", "peppolId": "1000000002", "legalRegistrationId": "CN-7654321", "legalRegistrationType": "CL", "legalRegistrationAuthorityName": "Abu Dhabi Department of Economic Development", "address": { "streetName": "Corniche Road 88", "cityName": "Abu Dhabi", "postalZone": "11111", "countrySubentity": "AUH", "countryCode": "AE" } }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00", "grossPriceAmount": "120.00", "baseQuantity": "1" }, "item": { "name": "Consulting services", "description": "Professional services for September 2026" }, "tax": { "category": "Z", "rate": "0" } } ], "taxTotal": { "taxAmount": "0.00", "taxSubtotals": [ { "category": "Z", "percent": "0.00", "taxableAmount": "1000.00", "taxAmount": "0.00" } ] }, "legalMonetaryTotal": { "lineExtensionAmount": "1000.00", "taxExclusiveAmount": "1000.00", "taxInclusiveAmount": "1000.00", "payableAmount": "1000.00" } } } }, "commercialInvoiceXmlMode": { "summary": "XML mode — UAE Commercial Invoice (480)", "description": "Issued when no VAT is charged. Carries all 49 MoF mandatory Commercial Invoice fields: the seller states its TIN instead of a VAT TRN, the buyer its legal registration, and every tax category is E, O or Z. The xml value is the UBL 2.1 document the API builds for the JSON example of the same name; it passes PINT-AE 1.0.4.", "value": { "inputType": "xml", "environment": "test", "documentType": "invoice", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "xml": "\n\n urn:peppol:pint:billing-1@ae-1\n urn:peppol:bis:billing\n 00000000\n CINV-2026-000123\n 3f2504e0-4f89-41d3-9a0c-000000000003\n 2026-09-16\n 2026-10-16\n 480\n Thank you for your business.\n AED\n \n \n 1000000001\n AZDAN Sample Supplier LLC\n \n Sheikh Zayed Road 12\n Office 401\n Dubai\n 00000\n DXB\n AE\n \n \n 1000000001\n TIN\n \n \n AZDAN Sample Supplier LLC\n CN-1234567\n \n \n \n \n 1000000002\n Emirates Buyer Trading LLC\n \n Corniche Road 88\n Abu Dhabi\n 11111\n AUH\n AE\n \n \n Emirates Buyer Trading LLC\n CN-7654321\n \n \n \n 30\n AE070331234567890123456\n \n \n Net 30 days\n \n \n 0.00\n \n 1000.00\n 0.00\n \n Z\n 0.00\n VAT\n \n \n \n \n 1000.00\n 1000.00\n 1000.00\n 1000.00\n \n \n 1\n 10\n 1000.00\n \n Professional services for September 2026\n Consulting services\n \n Z\n 0.00\n VAT\n \n \n \n 100.00\n 1\n \n false\n 20.00\n 120.00\n \n \n \n 1000.00\n \n 0.00\n \n \n \n" } }, "commercialCreditNoteJsonMode": { "summary": "JSON mode — UAE Commercial Credit Note (81) (81)", "description": "Reverses a commercial invoice. Same identity rules as 480.", "value": { "inputType": "json", "environment": "test", "documentType": "creditNote", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "payload": { "invoiceKind": "commercial", "invoiceNumber": "CCN-2026-000123", "uniqueIdentifierNumber": "3f2504e0-4f89-41d3-9a0c-000000000004", "issueDate": "2026-09-16", "currency": "AED", "transactionTypeCode": "00000000", "note": "Credit for returned goods.", "creditNoteReasonCode": "DL8.61.1.D", "billingReference": { "invoiceId": "CINV-2026-000123", "issueDate": "2026-09-16" }, "supplier": { "name": "AZDAN Sample Supplier LLC", "schemeId": "0235", "peppolId": "1000000001", "taxRegistrationId": "1000000001", "taxSchemeId": "TIN", "legalRegistrationId": "CN-1234567", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development Dubai", "address": { "streetName": "Sheikh Zayed Road 12", "additionalStreetName": "Office 401", "cityName": "Dubai", "postalZone": "00000", "countrySubentity": "DXB", "countryCode": "AE" } }, "customer": { "name": "Emirates Buyer Trading LLC", "schemeId": "0235", "peppolId": "1000000002", "legalRegistrationId": "CN-7654321", "legalRegistrationType": "CL", "legalRegistrationAuthorityName": "Abu Dhabi Department of Economic Development", "address": { "streetName": "Corniche Road 88", "cityName": "Abu Dhabi", "postalZone": "11111", "countrySubentity": "AUH", "countryCode": "AE" } }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00" }, "item": { "name": "Consulting services", "description": "Professional services for September 2026" }, "tax": { "category": "Z", "rate": "0" } } ], "taxTotal": { "taxAmount": "0.00", "taxSubtotals": [ { "category": "Z", "percent": "0.00", "taxableAmount": "1000.00", "taxAmount": "0.00" } ] }, "legalMonetaryTotal": { "lineExtensionAmount": "1000.00", "taxExclusiveAmount": "1000.00", "taxInclusiveAmount": "1000.00", "payableAmount": "1000.00" } } } }, "commercialCreditNoteXmlMode": { "summary": "XML mode — UAE Commercial Credit Note (81)", "description": "Reverses a commercial invoice. Same identity rules as 480. The xml value is the UBL 2.1 document the API builds for the JSON example of the same name; it passes PINT-AE 1.0.4.", "value": { "inputType": "xml", "environment": "test", "documentType": "creditNote", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "xml": "\n\n urn:peppol:pint:billing-1@ae-1\n urn:peppol:bis:billing\n 00000000\n CCN-2026-000123\n 3f2504e0-4f89-41d3-9a0c-000000000004\n 2026-09-16\n 81\n Credit for returned goods.\n AED\n \n DL8.61.1.D\n \n \n \n CINV-2026-000123\n 2026-09-16\n \n \n \n \n 1000000001\n AZDAN Sample Supplier LLC\n \n Sheikh Zayed Road 12\n Office 401\n Dubai\n 00000\n DXB\n AE\n \n \n 1000000001\n TIN\n \n \n AZDAN Sample Supplier LLC\n CN-1234567\n \n \n \n \n 1000000002\n Emirates Buyer Trading LLC\n \n Corniche Road 88\n Abu Dhabi\n 11111\n AUH\n AE\n \n \n Emirates Buyer Trading LLC\n CN-7654321\n \n \n \n 0.00\n \n 1000.00\n 0.00\n \n Z\n 0.00\n VAT\n \n \n \n \n 1000.00\n 1000.00\n 1000.00\n 1000.00\n \n \n 1\n 10\n 1000.00\n \n Professional services for September 2026\n Consulting services\n \n Z\n 0.00\n VAT\n \n \n \n 100.00\n 1\n \n false\n 0.00\n 100.00\n \n \n \n 1000.00\n \n 0.00\n \n \n \n" } }, "uaeScenarioJsonMode": { "summary": "JSON mode — Combined scenarios (380)", "description": "Positions 1, 4, 6 and 8 declared together (mask 10010101): the free-zone beneficiary (BTAE-01), the invoice period (IBG-14), the disclosed-agent principal (BTAE-14) and a deliver-to address abroad (IBG-13). Scenarios combine, and each companion element stays mandatory under its own rule — none is derived from a value the invoice already carries.", "value": { "inputType": "json", "environment": "test", "documentType": "invoice", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "payload": { "invoiceKind": "tax", "invoiceNumber": "INV-2026-000123", "uniqueIdentifierNumber": "3f2504e0-4f89-41d3-9a0c-000000000018", "issueDate": "2026-09-16", "dueDate": "2026-10-16", "currency": "AED", "transactionType": { "freeTradeZone": true, "summaryInvoice": true, "disclosedAgentBilling": true, "export": true }, "invoicePeriod": { "startDate": "2026-09-01", "endDate": "2026-09-30", "frequencyCode": "MTH" }, "paymentMeansCode": "30", "paymentAccountId": "AE070331234567890123456", "supplier": { "name": "AZDAN Sample Supplier LLC", "schemeId": "0235", "peppolId": "1000000001", "taxId": "100000000000103", "legalRegistrationId": "CN-1234567", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development Dubai", "address": { "streetName": "Sheikh Zayed Road 12", "additionalStreetName": "Office 401", "cityName": "Dubai", "postalZone": "00000", "countrySubentity": "DXB", "countryCode": "AE" } }, "customer": { "name": "Emirates Buyer Trading LLC", "schemeId": "0235", "peppolId": "1000000002", "taxId": "100000000000203", "address": { "streetName": "Corniche Road 88", "cityName": "Abu Dhabi", "postalZone": "11111", "countrySubentity": "AUH", "countryCode": "AE" }, "beneficiaryId": "FZ-BEN-778901" }, "agent": { "principalId": "PRINCIPAL-4471" }, "delivery": { "date": "2026-09-25", "address": { "streetName": "Hamngatan 4", "additionalStreetName": "Warehouse B", "cityName": "Goteborg", "postalZone": "41106", "countrySubentity": "Vastra Gotaland", "countryCode": "SE" } }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00" }, "item": { "name": "Consulting services", "description": "Professional services for September 2026" }, "tax": { "category": "S", "rate": "5" } } ], "taxTotal": { "taxAmount": "50.00", "taxSubtotals": [ { "category": "S", "percent": "5.00", "taxableAmount": "1000.00", "taxAmount": "50.00" } ] }, "legalMonetaryTotal": { "lineExtensionAmount": "1000.00", "taxExclusiveAmount": "1000.00", "taxInclusiveAmount": "1050.00", "payableAmount": "1050.00" } } } }, "exemptionReasonJsonMode": { "summary": "JSON mode — Mixed VAT categories (380)", "description": "Standard rated (S), zero rated (Z) and exempt (E) lines on one invoice. The VAT breakdown has one entry per category; the exempt line carries a VAT exemption reason code and no rate.", "value": { "inputType": "json", "environment": "test", "documentType": "invoice", "senderPeppolId": "0235:1000000001", "receiverPeppolId": "0235:1000000002", "payload": { "invoiceKind": "tax", "invoiceNumber": "INV-2026-000123", "uniqueIdentifierNumber": "3f2504e0-4f89-41d3-9a0c-000000000017", "issueDate": "2026-09-16", "dueDate": "2026-10-16", "currency": "AED", "transactionTypeCode": "00000000", "paymentMeansCode": "30", "paymentAccountId": "AE070331234567890123456", "supplier": { "name": "AZDAN Sample Supplier LLC", "schemeId": "0235", "peppolId": "1000000001", "taxId": "100000000000103", "legalRegistrationId": "CN-1234567", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development Dubai", "address": { "streetName": "Sheikh Zayed Road 12", "additionalStreetName": "Office 401", "cityName": "Dubai", "postalZone": "00000", "countrySubentity": "DXB", "countryCode": "AE" } }, "customer": { "name": "Emirates Buyer Trading LLC", "schemeId": "0235", "peppolId": "1000000002", "taxId": "100000000000203", "address": { "streetName": "Corniche Road 88", "cityName": "Abu Dhabi", "postalZone": "11111", "countrySubentity": "AUH", "countryCode": "AE" } }, "lines": [ { "id": "1", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00" }, "item": { "name": "Consulting services", "description": "Professional services for September 2026" }, "tax": { "category": "S", "rate": "5" } }, { "id": "2", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00" }, "item": { "name": "International freight", "description": "Zero-rated international transport of goods" }, "tax": { "category": "Z", "rate": "0" } }, { "id": "3", "quantity": "10", "unitCode": "EA", "lineExtensionAmount": "1000.00", "price": { "priceAmount": "100.00" }, "item": { "name": "Financial service fee", "description": "Exempt financial service" }, "tax": { "category": "E", "exemptionReasonCode": "VATEX-AE-EXEMPT-FINANCIAL" } } ], "taxTotal": { "taxAmount": "50.00", "taxSubtotals": [ { "category": "S", "percent": "5.00", "taxableAmount": "1000.00", "taxAmount": "50.00" }, { "category": "Z", "percent": "0.00", "taxableAmount": "1000.00", "taxAmount": "0.00" }, { "category": "E", "taxableAmount": "1000.00", "taxAmount": "0.00" } ] }, "legalMonetaryTotal": { "lineExtensionAmount": "3000.00", "taxExclusiveAmount": "3000.00", "taxInclusiveAmount": "3050.00", "payableAmount": "3050.00" } } } } } } } }, "responses": { "202": { "description": "Accepted for delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" }, "examples": { "accepted": { "summary": "Accepted for delivery", "value": { "transactionId": "txn_1789562400000_9f3a1c2b", "status": "queued", "valid": true, "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "correlationId": "cor_1789562400000_4d5e6f70", "as4MessageId": "f0debc61-215c-4e0a-9d1b-2a7c3e4f5a6b@peppol.azdanapps.com", "sbdhInstanceId": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "idempotent": false, "warnings": [], "validatorPhormSkipped": false, "message": "Invoice accepted for Peppol delivery.", "documents": { "invoiceXml": { "available": true, "fileId": "file_01J9Z3Q7M8K2N4P6R8T0V2X4Y6", "fileName": "txn_1789562400000_9f3a1c2b.xml", "contentType": "application/xml", "downloadUrl": "/api/integrations/peppol/transactions/txn_1789562400000_9f3a1c2b/files/invoice-xml" }, "invoicePdf": { "available": false, "fileId": null, "fileName": null, "contentType": "application/pdf", "downloadUrl": null, "reason": "not_generated" }, "sbdXml": { "available": false, "fileId": null, "fileName": null, "contentType": "application/xml", "downloadUrl": null, "reason": "not_stored" }, "tddXml": { "available": false, "fileId": null, "fileName": null, "contentType": "application/xml", "downloadUrl": null, "reason": "not_generated" }, "mlsXml": { "available": false, "fileId": null, "fileName": null, "contentType": "application/xml", "downloadUrl": null, "reason": "not_received" }, "payloadXml": { "available": false, "privileged": true, "requiredScope": "peppol:payload:read", "contentType": "application/xml", "downloadUrl": null, "reason": "not_in_object_storage" } } } }, "idempotentReplay": { "summary": "Same Idempotency-Key again — the original transaction, nothing sent twice", "value": { "transactionId": "txn_1789562400000_9f3a1c2b", "status": "sending", "valid": true, "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "correlationId": "cor_1789562400000_4d5e6f70", "as4MessageId": "f0debc61-215c-4e0a-9d1b-2a7c3e4f5a6b@peppol.azdanapps.com", "sbdhInstanceId": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "idempotent": true, "warnings": [], "validatorPhormSkipped": false, "message": "Existing transaction returned (idempotent replay)." } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "502": { "$ref": "#/components/responses/UpstreamError" } }, "security": [ { "ApiKeyBearer": [] } ], "x-azdan-access": "apiKey", "x-azdan-scopes": [ "peppol:submit", "transactions:submit" ] } }, "/api/integrations/peppol/transactions": { "get": { "operationId": "listTransactions", "summary": "List transactions", "description": "Paginated list of the tenant's transactions. Supports two pagination modes:\n\n- **Cursor mode** (default): Pass `limit` and optionally `cursor`.\n Recommended for sync jobs and large datasets.\n- **Page mode**: Pass `page` and `pageSize`. Backward compatible for\n UI browsing.\n\nIf both `page`/`pageSize` and `limit`/`cursor` are absent, cursor mode\nis used with default limit=50.\n\n\n**Access:** Tenant API key (`Authorization: Bearer azd_…`).\n\n**API-key scopes (any one):** `transactions:read`, `peppol:read`, `peppol:submit`", "tags": [ "Integration API · Peppol" ], "parameters": [ { "$ref": "#/components/parameters/CursorLimit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Sort" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/IncludeParam" }, { "$ref": "#/components/parameters/FilterDirection" }, { "$ref": "#/components/parameters/FilterStatus" }, { "$ref": "#/components/parameters/FilterEnvironment" }, { "$ref": "#/components/parameters/FilterDocumentType" }, { "$ref": "#/components/parameters/FilterSenderPeppolId" }, { "$ref": "#/components/parameters/FilterReceiverPeppolId" }, { "$ref": "#/components/parameters/FilterPeppolParticipantId" }, { "$ref": "#/components/parameters/FilterSubsidiaryId" }, { "$ref": "#/components/parameters/FilterCorrelationId" }, { "$ref": "#/components/parameters/FilterAs4MessageId" }, { "$ref": "#/components/parameters/FilterApCoreMessageId" }, { "$ref": "#/components/parameters/FilterSbdhInstanceId" }, { "$ref": "#/components/parameters/FilterIdempotencyKey" }, { "$ref": "#/components/parameters/FilterDateFrom" }, { "$ref": "#/components/parameters/FilterDateTo" }, { "$ref": "#/components/parameters/FilterMessageId" }, { "$ref": "#/components/parameters/FilterSearch" } ], "responses": { "200": { "description": "Transaction list", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CursorListResponse" }, { "$ref": "#/components/schemas/PageListResponse" } ] }, "examples": { "cursorMode": { "summary": "Cursor pagination", "value": { "items": [ { "transactionId": "txn_1715690640123_a1b2c3d4", "direction": "outbound", "status": "delivered", "documentType": "invoice", "sender": { "participantId": "0235:1000000001", "name": "Acme Trading LLC" }, "receiver": { "participantId": "0235:1000000002", "name": "BuyerCo" }, "environment": "production", "createdAt": "2026-05-14T10:00:00.000Z" } ], "pagination": { "mode": "cursor", "limit": 50, "nextCursor": "eyJzIjoiY3JlYXRlZEF0Iiw...", "prevCursor": null, "hasNext": true } } }, "pageMode": { "summary": "Page pagination (backward compatible)", "value": { "transactions": [ { "transactionId": "txn_1715690640123_a1b2c3d4", "direction": "outbound", "status": "delivered" } ], "pagination": { "page": 1, "pageSize": 25, "total": 142, "totalPages": 6, "hasMore": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ApiKeyBearer": [] } ], "x-azdan-access": "apiKey", "x-azdan-scopes": [ "transactions:read", "peppol:read", "peppol:submit" ] } }, "/api/integrations/peppol/transactions/by-message/{messageId}": { "get": { "operationId": "getTransactionByMessageId", "summary": "Look up transaction by AS4 message ID", "description": "Find a transaction by its AS4/AP Core message ID. Useful for correlating\ntransport-level IDs from AP logs or network receipts.\n\n\n**Access:** Tenant API key (`Authorization: Bearer azd_…`).\n\n**API-key scopes (any one):** `transactions:read`, `peppol:read`, `peppol:submit`", "tags": [ "Integration API · Peppol" ], "parameters": [ { "name": "messageId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "f0debc61-215c-4d16-9d33-ca5d126ccbb3@peppol.azdanapps.com" } ], "responses": { "200": { "description": "Transaction detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyBearer": [] } ], "x-azdan-access": "apiKey", "x-azdan-scopes": [ "transactions:read", "peppol:read", "peppol:submit" ] } }, "/api/integrations/peppol/transactions/by-idempotency/{idempotencyKey}": { "get": { "operationId": "getTransactionByIdempotencyKey", "summary": "Look up transaction by Idempotency-Key", "description": "Return the transaction that was originally created with the given\n`Idempotency-Key`. Keys are scoped per tenant, so this is a deterministic\nsingle-row lookup. Use this to confirm whether a previous submit attempt\nsucceeded without retrying it.\n\n\n**Access:** Tenant API key (`Authorization: Bearer azd_…`).", "tags": [ "Integration API · Peppol" ], "parameters": [ { "name": "idempotencyKey", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "example": "erp-invoice-2026-0001" } ], "responses": { "200": { "description": "Transaction summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyBearer": [] } ], "x-azdan-access": "apiKey", "x-azdan-scopes": [ "transactions:read", "peppol:read", "peppol:submit" ] } }, "/api/integrations/peppol/transactions/{transactionId}/tdd": { "get": { "operationId": "getTransactionTdd", "summary": "Tax Data Document generated for a transaction", "description": "Tax Data Documents are generated automatically by AZDAN. Do not submit a TDD. Use the invoice transaction's TDD endpoint to inspect the generated TDD status and download it when available.\n\nResolution follows the explicit parent linkage recorded by the access point (never a time or sender guess), so on a self-send the TDD returned is the one generated for THIS outbound document. The download route returns JSON with a short-lived signed URL and needs the privileged peppol:payload:read scope; documents.tddXml / …/files/tdd-xml offer the same file under the ordinary document-read scopes.\n\nOn the enriched detail of an invoice, ap.isTdd is always false and ap.tddStatus is always null — they describe the row itself, not the TDD generated for it. The generated TDD's delivery status is tdd.status on the TDD endpoint.\n\nRequired scope: any of x-azdan-scopes (a default key qualifies).\n\n**Access:** Tenant API key (`Authorization: Bearer azd_…`).", "tags": [ "Integration API · Peppol" ], "parameters": [ { "$ref": "#/components/parameters/TransactionIdPath" } ], "responses": { "200": { "description": "TDD metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "tdd" ], "properties": { "tdd": { "$ref": "#/components/schemas/TddMetadata" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyBearer": [] } ], "x-azdan-access": "apiKey", "x-azdan-scopes": [ "transactions:read", "peppol:read", "peppol:submit" ] } }, "/api/integrations/peppol/transactions/{transactionId}/tdd/download": { "get": { "operationId": "getTransactionTddDownload", "summary": "Signed download link for the generated Tax Data Document", "description": "Same resolution as …/tdd, plus a short-lived signed downloadUrl for the TDD XML. Returns JSON (not a redirect). Resolution follows the explicit parent linkage recorded by the access point (never a time or sender guess), so on a self-send the TDD returned is the one generated for THIS outbound document. The download route returns JSON with a short-lived signed URL and needs the privileged peppol:payload:read scope; documents.tddXml / …/files/tdd-xml offer the same file under the ordinary document-read scopes.\n\n**Access:** Tenant API key (`Authorization: Bearer azd_…`).", "tags": [ "Integration API · Peppol" ], "parameters": [ { "$ref": "#/components/parameters/TransactionIdPath" }, { "name": "ttlSeconds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Requested link lifetime; the server may cap it." } ], "responses": { "200": { "description": "TDD metadata with a signed download URL", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/TddMetadata" }, { "type": "object", "properties": { "downloadUrl": { "type": "string", "format": "uri" }, "ttlSeconds": { "type": "integer" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyBearer": [] } ], "x-azdan-access": "apiKey", "x-azdan-scopes": [ "peppol:payload:read" ] } }, "/api/integrations/peppol/transactions/{transactionId}/files/{docKind}": { "get": { "operationId": "getIntegrationsPeppolTransactionsByTransactionIdFilesByDocKind", "summary": "API-key authenticated aliases for the unified documents contract", "description": "API-key authenticated aliases for the unified documents contract. These\nmirror the tenant portal download routes but live under the integration\nnamespace so ERP/webhook consumers can use their AZDAN API key.\n\n**Access:** Tenant API key (`Authorization: Bearer azd_…`).\n\nSpecified per document kind in the public Integration API reference: `/api/integrations/peppol/transactions/{transactionId}/files/invoice-xml`, `/api/integrations/peppol/transactions/{transactionId}/files/invoice-pdf`, `/api/integrations/peppol/transactions/{transactionId}/files/sbd-xml`, `/api/integrations/peppol/transactions/{transactionId}/files/tdd-xml`, `/api/integrations/peppol/transactions/{transactionId}/files/mls-xml`.\n\n**API-key scopes (any one):** `peppol:read`, `transactions:read`, `peppol:submit`", "tags": [ "Integration API · Peppol" ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "docKind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "invoice-xml", "invoice-pdf", "sbd-xml", "tdd-xml", "mls-xml" ] } } ], "responses": { "200": { "description": "File streamed through the Platform API.", "headers": { "Content-Disposition": { "schema": { "type": "string", "example": "attachment; filename=\"INV-10001.xml\"" } }, "Cache-Control": { "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/xml": { "schema": { "type": "string", "format": "binary" } } } }, "302": { "description": "Redirect to a short-lived signed download URL.", "headers": { "Location": { "description": "Short-lived signed download URL.", "schema": { "type": "string", "format": "uri" } }, "Cache-Control": { "schema": { "type": "string", "example": "no-store" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyBearer": [] } ], "x-azdan-access": "apiKey", "x-azdan-scopes": [ "peppol:read", "transactions:read", "peppol:submit" ] } }, "/api/integrations/peppol/transactions/{transactionId}": { "get": { "operationId": "getTransaction", "summary": "Get enriched transaction detail", "description": "Returns a full enriched view of a single transaction including:\n- `transaction` — platform transaction fields\n- `platform` — correlation/idempotency/webhook summary\n- `ap` — AP Core link status, AS4/SBDH IDs, timestamps, errors\n- `storage` — primary storage info (S3 key, content type, size)\n- `files` — list of associated files (payload, SBDH, MLR, etc.)\n- `links` — HATEOAS links to related endpoints (self, events, xml)\n\nAP matching uses a prioritized strategy:\n1. Exact match on `sbdhInstanceId`\n2. Exact match on `apCoreMessageId` (AS4 message ID)\n3. Fuzzy match on sender+receiver+docType+process+createdAt±5min\n4. If multiple fuzzy matches, returns `ap.linkAmbiguous: true`\n\n\n**Access:** Tenant API key (`Authorization: Bearer azd_…`).\n\n**API-key scopes (any one):** `transactions:read`, `peppol:read`, `peppol:submit`", "tags": [ "Integration API · Peppol" ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "txn_1715690640123_a1b2c3d4" } ], "responses": { "200": { "description": "Enriched transaction detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichedTransactionDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyBearer": [] } ], "x-azdan-access": "apiKey", "x-azdan-scopes": [ "transactions:read", "peppol:read", "peppol:submit" ] } }, "/api/integrations/peppol/transactions/{transactionId}/xml": { "get": { "operationId": "getTransactionXml", "summary": "Download XML business payload", "description": "Generates a time-limited presigned S3 URL for the XML business payload\nand redirects (303) to it. The `Content-Type` header is set to\n`application/xml`. The presigned URL expires after 60 seconds.\n\nRequires scope: `peppol:payload:read`.\n\nReturns 409 if the payload is not available in S3 (e.g., only exists\nin a legacy local filesystem path).\n\n\n**Access:** Tenant API key (`Authorization: Bearer azd_…`).", "tags": [ "Integration API · Peppol" ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "303": { "description": "Redirect to presigned S3 URL", "headers": { "Location": { "description": "Presigned S3 download URL (expires in 60s)", "schema": { "type": "string", "format": "uri" } }, "Content-Type": { "schema": { "type": "string", "example": "application/xml" } }, "Cache-Control": { "schema": { "type": "string", "example": "no-store" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Payload not available in object storage yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "PAYLOAD_NOT_IN_OBJECT_STORAGE", "message": "XML payload is not available in object storage." } } } } } }, "security": [ { "ApiKeyBearer": [] } ], "x-azdan-access": "apiKey", "x-azdan-scopes": [ "peppol:payload:read" ] } }, "/api/integrations/peppol/transactions/{transactionId}/events": { "get": { "operationId": "getTransactionEvents", "summary": "Get webhook events for a transaction", "description": "Retrieve the webhook event timeline for a transaction. Shows every\nlifecycle event emitted, delivery status, and any errors. Events are\nsorted chronologically (oldest first).\n\n\n**Access:** Tenant API key (`Authorization: Bearer azd_…`).\n\n**API-key scopes (any one):** `transactions:read`, `peppol:read`, `peppol:submit`", "tags": [ "Integration API · Peppol" ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Event timeline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsResponse" }, "examples": { "timeline": { "summary": "Full outbound lifecycle", "value": { "events": [ { "eventId": "evt_txn_submitted_abc123", "type": "transaction.submitted", "deliveryStatus": "delivered", "payload": { "event": "transaction.submitted", "transactionId": "txn_1715690640123_a1b2c3d4", "status": "queued", "direction": "outbound", "environment": "production", "sender": "0235:1000000001", "receiver": "0235:1000000002" }, "createdAt": "2026-05-14T10:00:00.000Z", "deliveredAt": "2026-05-14T10:00:01.000Z", "attempts": 1, "lastError": null }, { "eventId": "evt_ap_a1b2c3d4e5f6g7h8", "type": "ap.outbound.delivered", "deliveryStatus": "delivered", "payload": { "event": "ap.outbound.delivered", "status": "delivered", "direction": "outbound" }, "createdAt": "2026-05-14T10:00:04.000Z", "deliveredAt": "2026-05-14T10:00:05.000Z", "attempts": 1, "lastError": null } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "ApiKeyBearer": [] } ], "x-azdan-access": "apiKey", "x-azdan-scopes": [ "transactions:read", "peppol:read", "peppol:submit" ] } }, "/api/tenant/transactions/{transactionId}/files/{docKind}": { "get": { "operationId": "getTenantTransactionsByTransactionIdFilesByDocKind", "summary": "Download a transaction document (legacy API-key URL)", "description": "Backward-compatible URL for Postman imports and webhook payloads that still point integrations at `/api/tenant/transactions/{id}/files/{kind}`. The canonical API-key URL is `GET /api/integrations/peppol/transactions/{transactionId}/files/{docKind}`; both run the same handler.\n\nOnly requests with `Authorization: Bearer azd_live_…` / `azd_test_…` are handled here; any other caller (tenant JWT or session cookie) falls through to the Tenant Console download route on the same path, which uses session authentication.\n\nThe file must belong to both the transaction and the key's tenant. The bytes are streamed (`Content-Disposition: attachment`, `Cache-Control: no-store`) or the call answers `302` to a short-lived signed URL; storage coordinates are never returned. A missing document answers `404` naming the document and why it is absent (`details.reason`: `not_generated`, `metadata_only`, `not_received`, `not_stored_for_outbound`, `not_stored`, `transaction_not_found`). Each download is audited (`storage.document.download`).\n\n**Scopes (any one):** `peppol:read`, `transactions:read`, `peppol:submit`. Rate-limited with the shared per-API-key submit limiter.\n\n**Access:** Tenant API key (`Authorization: Bearer azd_…`).\n\nSpecified per document kind in the public Integration API reference: `/api/tenant/transactions/{transactionId}/files/invoice-xml`, `/api/tenant/transactions/{transactionId}/files/invoice-pdf`, `/api/tenant/transactions/{transactionId}/files/sbd-xml`, `/api/tenant/transactions/{transactionId}/files/tdd-xml`, `/api/tenant/transactions/{transactionId}/files/mls-xml`.\n\n**API-key scopes (any one):** `peppol:read`, `transactions:read`, `peppol:submit`", "tags": [ "Integration API · Documents" ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "docKind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "invoice-xml", "invoice-pdf", "sbd-xml", "tdd-xml", "mls-xml" ] } } ], "responses": { "200": { "description": "File streamed. `Content-Type` is the stored type (`application/xml` or `application/pdf`).", "headers": { "Content-Disposition": { "schema": { "type": "string", "example": "attachment; filename=\"INV-10001.xml\"" } }, "Cache-Control": { "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "302": { "description": "Redirect to a short-lived signed download URL.", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } }, "Cache-Control": { "schema": { "type": "string", "example": "no-store" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "description": "The document is not available for this transaction, or the transaction is not the key's tenant's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "document": { "type": "string" }, "available": { "type": "boolean" }, "reason": { "type": "string" }, "expected": { "type": "boolean" } } } } } } }, "example": { "error": { "code": "NOT_FOUND", "message": "Tax Data Document has not been generated for this transaction", "details": { "document": "tddXml", "available": false, "reason": "not_generated", "expected": true } } } } } }, "429": { "description": "Rate limit exceeded (per API key). Answered by express-rate-limit's default handler: plain-text body `Too many requests, please try again later.` with standard `RateLimit-*` headers.", "content": { "text/plain": { "schema": { "type": "string", "format": "binary" } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "ApiKeyBearer": [] } ], "x-azdan-access": "apiKey", "x-azdan-scopes": [ "peppol:read", "transactions:read", "peppol:submit" ] } }, "/api/tenant/config/preferences/{tenantId}": { "get": { "operationId": "getTenantConfigPreferencesByTenantId", "summary": "Get the tenant's own preferences", "description": "Returns the caller's own `tenant_preferences` document. The `{tenantId}` path segment must equal the principal's tenant, otherwise 403 (`cross-tenant access denied`). Webhook entries are returned as stored, including `secretEnc`. 404 when none has been written.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The tenant preferences document.", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string" }, "schemaVersion": { "type": "integer" }, "retries": { "type": "object", "properties": { "outbound.max-attempts": { "type": "integer" } } }, "notifications": { "type": "object", "properties": { "email.failures": { "type": "array", "items": { "type": "string" } } } }, "version": { "type": "integer" }, "updatedAt": { "type": "string" }, "updatedBy": { "type": "string" }, "updatedFromIp": { "type": "string" }, "changeRef": { "type": "string" } } }, "example": { "_id": "tnt_7Q2X…", "schemaVersion": 1, "retries": { "outbound.max-attempts": 5 }, "notifications": { "email.failures": [ "o***@example.com" ] }, "version": 3, "updatedAt": "2026-10-21T09:14:03.000Z", "updatedBy": "usr_3Hd…", "updatedFromIp": "10.0.1.***", "changeRef": "6717a5e1…77c0" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "description": "Not found. This route answers with a bare code and no `message`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" } } } } }, "example": { "error": { "code": "NOT_FOUND" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "put": { "operationId": "putTenantConfigPreferencesByTenantId", "summary": "Create or update the tenant's own preferences", "description": "Writes the caller's own `tenant_preferences` document (same pipeline as the admin route: `reason` and `expectedVersion` required, JSON Schema validation, optimistic concurrency, change history and audit). `{tenantId}` must equal the principal's tenant. The route itself checks only tenant ownership, not the tenant role, so any tenant user of the tenant can write.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedVersion": { "type": "integer" }, "reason": { "type": "string" }, "payload": { "type": "object", "properties": { "retries": { "type": "object", "properties": { "outbound.max-attempts": { "type": "integer" } } }, "notifications": { "type": "object", "properties": { "email.failures": { "type": "array", "items": { "type": "string" } } } } } } } }, "example": { "expectedVersion": 2, "reason": "Add finance mailbox for failure alerts", "payload": { "retries": { "outbound.max-attempts": 5 }, "notifications": { "email.failures": [ "o***@example.com" ] } } } } } }, "responses": { "200": { "description": "The document after the write.", "content": { "application/json": { "schema": { "type": "object", "properties": { "doc": { "type": "object", "properties": { "_id": { "type": "string" }, "schemaVersion": { "type": "integer" }, "retries": { "type": "object", "properties": { "outbound.max-attempts": { "type": "integer" } } }, "notifications": { "type": "object", "properties": { "email.failures": { "type": "array", "items": { "type": "string" } } } }, "version": { "type": "integer" }, "updatedAt": { "type": "string" }, "updatedBy": { "type": "string" }, "updatedFromIp": { "type": "string" }, "changeRef": { "type": "string" } } }, "changed": { "type": "boolean" } } }, "example": { "doc": { "_id": "tnt_7Q2X…", "schemaVersion": 1, "retries": { "outbound.max-attempts": 5 }, "notifications": { "email.failures": [ "o***@example.com" ] }, "version": 3, "updatedAt": "2026-10-21T09:14:03.000Z", "updatedBy": "usr_3Hd…", "updatedFromIp": "10.0.1.***", "changeRef": "6717a5e1…77c0" }, "changed": true } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "409": { "$ref": "#/components/responses/ErrConflict" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/terms": { "get": { "operationId": "getTenantTerms", "summary": "Where the signed-in tenant stands against the current agreement: the current version,…", "description": "Where the signed-in tenant stands against the current agreement: the\ncurrent version, the acceptance on record (version, date, who), whether an\nacceptance is still required, and whether THIS user may give it.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/terms/accept": { "post": { "operationId": "postTenantTermsAccept", "summary": "Records the administrator's acceptance of the current agreement for the tenant…", "description": "Records the administrator's acceptance of the current agreement for the\ntenant (receipt row + tenant summary) and lifts the sign-in gate on the\nnext request. 409 TERMS_VERSION_OUTDATED when `version` is not the current one.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1, "maxLength": 16 }, "accepted": { "const": true }, "locale": { "type": "string", "enum": [ "en", "ar" ] } }, "required": [ "version", "accepted" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/fta/onboarding/confirm": { "post": { "operationId": "postTenantFtaOnboardingConfirm", "summary": "Confirm onboarding: register the Peppol participant and link in EmaraTax", "description": "Step 3 of onboarding for a signed-in tenant, after the taxpayer saw FTA's verification. Requires `acknowledged: true` (literal) and a session in status `verified` that has not expired.\n\n1. Environment guard (session's pinned plane = live gateway plane).\n2. The participant id is **derived** from the FTA-verified TIN (`0235:`); a `peppolId` in the body may only confirm it (`400 FTA_PEPPOL_ID_MISMATCH`).\n3. A tenant that already holds an active linkage for this TIN is refused (`409 FTA_EXISTING_LINKAGE_ACTION_REQUIRED` — use the reverify/offboard routes).\n4. Register the participant (idempotent; reused when this tenant already owns it, `409 PEPPOL_ID_ALREADY_ASSIGNED` when another tenant does) on the given or default subsidiary, C1 country defaulting to the subsidiary's, else `AE`.\n5. Publish it on the AZDAN SMP + SML (unless `FTA_ONBOARDING_SMP_PUBLISH=off`).\n6. Call FTA API-5 `crregupdate` action 1. Once FTA has reported `Active`, a re-confirmation never calls API-5 again.\n7. Record the durable FTA profile and spend the session.\n\n`linked` is true only when FTA's `onboardingStatus` is `Active`. A registry step that is pending, blocked (`crreg.status: \"contract_blocked\"` with `missingContractFacts`) or failed is reported as data in `crreg`; `crreg.retryable: true` means the same session may submit again. Side effects: audit `fta.onboarding.confirmed`; the `fta_onboarded` email when linked.\n\n`tenantId` always comes from the session principal; body fields `tenantId`, `environment` and `tin` are ignored (stripped by the schema). Responses carry `Cache-Control: no-store, private, max-age=0`. Errors are `{ error: { code, message, correlationId } }` with no upstream body. Counts against the tenant write limiter (`RATE_LIMIT_WRITE_MAX`, default 60/min per tenant).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "EmaraTax (FTA)" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1, "maxLength": 512 }, "acknowledged": { "const": true }, "peppolId": { "type": "string", "pattern": "^[A-Za-z0-9]{2,8}:.+$" }, "subsidiaryId": { "type": "string", "minLength": 1, "maxLength": 120 }, "c1CountryCode": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound", "both" ] }, "label": { "type": "string", "maxLength": 120 }, "termsAccepted": { "type": "boolean" }, "termsVersion": { "type": "string", "maxLength": 16 }, "termsLocale": { "type": "string", "enum": [ "en", "ar" ] }, "clientIp": { "type": "string", "maxLength": 64 }, "userAgent": { "type": "string", "maxLength": 512 }, "linkToken": { "type": "string", "minLength": 20, "maxLength": 200 }, "targetConfirmed": { "type": "boolean" } }, "required": [ "sessionId", "acknowledged" ] }, "example": { "sessionId": "kM3v…", "acknowledged": true, "peppolId": "0235:1004****59", "subsidiaryId": "sub_…", "c1CountryCode": "AE", "direction": "both", "label": "Head office" } } } }, "responses": { "200": { "description": "Participant registered; `crreg` and `linked` report the EmaraTax outcome.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "correlationId": { "type": "string" }, "participant": { "type": "object", "properties": { "participantId": { "type": "string" }, "peppolId": { "type": "string" }, "environment": { "type": "string" }, "direction": { "type": "string" }, "status": { "type": "string" }, "reused": { "type": "boolean" } } }, "crreg": { "type": "object", "properties": { "status": { "type": "string" }, "msgCode": { "type": "string" }, "errorCode": { "type": "null" }, "onboardingStatus": { "type": "string" }, "recordUpdateTimestamp": { "type": "string" }, "retryable": { "type": "boolean" }, "reused": { "type": "boolean" }, "action": { "type": "integer" }, "missingContractFacts": { "type": "null" } } }, "smpPublish": { "type": "object", "properties": { "status": { "type": "string" }, "verifiedPublished": { "type": "boolean" }, "held": { "type": "boolean" }, "documentTypes": { "type": "array", "items": { "type": "string" } } } }, "linked": { "type": "boolean" } } }, "example": { "ok": true, "correlationId": "fta-3c9e…", "participant": { "participantId": "ppt_…", "peppolId": "0235:1004****59", "environment": "production", "direction": "both", "status": "active", "reused": false }, "crreg": { "status": "ok", "msgCode": "…", "errorCode": null, "onboardingStatus": "Active", "recordUpdateTimestamp": "2026-10-24T09:25:31Z", "retryable": false, "reused": false, "action": 1, "missingContractFacts": null }, "smpPublish": { "status": "published", "verifiedPublished": true, "held": false, "documentTypes": [ "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##…" ] }, "linked": true } } } }, "400": { "description": "`acknowledged` missing/false, or `peppolId` differs from the derived id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_PEPPOL_ID_MISMATCH", "message": "…", "correlationId": "fta-3c9e…" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "description": "Unknown session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_SESSION_NOT_FOUND", "message": "…", "correlationId": "fta-3c9e…" } } } } }, "409": { "description": "Session not verified, participant id underivable or owned by another tenant, an existing linkage requires reverify/offboard, or the environment changed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_NOT_VERIFIED", "message": "…", "correlationId": "fta-3c9e…" } } } } }, "410": { "description": "The session expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_SESSION_EXPIRED", "message": "…", "correlationId": "fta-3c9e…" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" }, "503": { "description": "SMP publication not configured, environment unknown, or the profile could not be persisted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_PEPPOL_PUBLISH_NOT_CONFIGURED", "message": "…", "correlationId": "fta-3c9e…" } } } } } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/fta/link/start": { "post": { "operationId": "postTenantFtaLinkStart", "summary": "mint the link intent for the signed-in administrator and tell the portal where EmaraTax is", "description": "mint the link intent for the signed-in administrator\nand tell the portal where EmaraTax is. The clear token is returned ONCE, for the portal\nto place in its HttpOnly cookie; it is never stored and never echoed again.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "EmaraTax (FTA)" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/fta/link/status": { "get": { "operationId": "getTenantFtaLinkStatus", "summary": "the Connect screen's facts (no credential, no token)", "description": "the Connect screen's facts (no credential, no token).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "EmaraTax (FTA)" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/fta/linkage/context": { "post": { "operationId": "postTenantFtaLinkageContext", "summary": "Bind a session to the tenant and get the linkage context", "description": "The first call the portal makes for a session once the user is signed in. Answers whether the tenant already holds an FTA linkage for **this session's taxpayer** in the session's environment.\n\n- The taxpayer is taken from the session (bound TIN, else the TIN EmaraTax sent on a management redirect, else the FTA-verified TIN) — never typed by the user. A management session without a TIN is bound only when the tenant has exactly one linked taxpayer in that environment.\n- **No linkage** → `existingLinkage: false`; onboarding continues. A management redirect without a linkage → `409 FTA_LINKAGE_NOT_FOUND`.\n- **Linkage found** → the session is **bound** (claimed) to the tenant and TIN, and the response carries the durable profile, offboarding/reverification state, and whether API-5 (`registryReady`) and the SMP removal (`smpReady`) can run on this deployment (missing configuration names only).\n- A session claimed by another tenant → `403 FTA_SESSION_TENANT_MISMATCH`; a management TIN that is not this tenant's → `403 FTA_MANAGEMENT_TIN_MISMATCH`. A consumed session still answers (`consumed: true`) so the outcome screen can render.\n\nNo external call (FTA/SMP). Any tenant role may call it.\n\n`tenantId` always comes from the session principal; body fields `tenantId`, `environment` and `tin` are ignored (stripped by the schema). Responses carry `Cache-Control: no-store, private, max-age=0`. Errors are `{ error: { code, message, correlationId } }` with no upstream body. Counts against the tenant write limiter (`RATE_LIMIT_WRITE_MAX`, default 60/min per tenant).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "EmaraTax (FTA)" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "sessionId" ] }, "example": { "sessionId": "kM3v…" } } } }, "responses": { "200": { "description": "Context. Example: existing linkage, management entry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "correlationId": { "type": "string" }, "existingLinkage": { "type": "boolean" }, "consumed": { "type": "boolean" }, "environment": { "type": "string" }, "entry": { "type": "string" }, "managementTin": { "type": "string" }, "requestId": { "type": "string" }, "linkage": { "type": "object", "properties": { "tenantId": { "type": "string" }, "environment": { "type": "string" }, "tin": { "type": "string" }, "peppolId": { "type": "string" }, "participantId": { "type": "string" }, "aspName": { "type": "string" }, "claimedAt": { "type": "string" } } }, "operation": { "type": "null" }, "verification": { "type": "null" }, "verificationClassification": { "type": "null" }, "verificationTinMismatch": { "type": "boolean" }, "verifyAttemptsRemaining": { "type": "integer" }, "hintedTinMatches": { "type": "boolean" }, "profile": { "type": "object", "properties": { "tin": { "type": "string" }, "peppolId": { "type": "string" }, "participantId": { "type": "string" }, "peppolStatus": { "type": "string" }, "entityNameEn": { "type": "string" }, "entityNameAr": { "type": "string" }, "vatTrn": { "type": "string" }, "legalType": { "type": "string" }, "effectiveDate": { "type": "string" }, "registeredAdminEmail": { "type": "string" }, "mobile": { "type": "string" }, "onboardingStatus": { "type": "string" }, "linkedAt": { "type": "string" }, "overallStatus": { "type": "string" } } }, "offboarding": { "type": "object", "properties": { "stage": { "type": "string" }, "pending": { "type": "boolean" }, "participantRemoved": { "type": "boolean" }, "smpUnpublished": { "type": "boolean" }, "smpUnpublish": { "type": "null" }, "registry": { "type": "null" } } }, "reverification": { "type": "object", "properties": { "lastCompletedAt": { "type": "null" }, "count": { "type": "integer" } } }, "registryReady": { "type": "boolean" }, "registryBlockers": { "type": "array", "items": {} }, "smpReady": { "type": "boolean" }, "smpBlockers": { "type": "array", "items": {} }, "summary": { "type": "object", "properties": { "tin": { "type": "string" }, "peppolId": { "type": "string" }, "verificationStatus": { "type": "string" }, "linkageStatus": { "type": "string" }, "aspName": { "type": "string" } } } } }, "example": { "ok": true, "correlationId": "fta-3c9e…", "existingLinkage": true, "consumed": false, "environment": "production", "entry": "management", "managementTin": "1004****59", "requestId": "far_…", "linkage": { "tenantId": "tnt_7Q2X…", "environment": "production", "tin": "1004****59", "peppolId": "0235:1004****59", "participantId": "ppt_…", "aspName": "AZDAN", "claimedAt": "2026-10-24T09:23:55.000Z" }, "operation": null, "verification": null, "verificationClassification": null, "verificationTinMismatch": false, "verifyAttemptsRemaining": 3, "hintedTinMatches": true, "profile": { "tin": "1004****59", "peppolId": "0235:1004****59", "participantId": "ppt_…", "peppolStatus": "active", "entityNameEn": "Example Trading LLC", "entityNameAr": "…", "vatTrn": "1004****59003", "legalType": "LLC", "effectiveDate": "2026-01-01", "registeredAdminEmail": "o***@example.com", "mobile": "+97155****67", "onboardingStatus": "Active", "linkedAt": "2026-09-02T10:11:00.000Z", "overallStatus": "linked" }, "offboarding": { "stage": "none", "pending": false, "participantRemoved": false, "smpUnpublished": false, "smpUnpublish": null, "registry": null }, "reverification": { "lastCompletedAt": null, "count": 0 }, "registryReady": true, "registryBlockers": [], "smpReady": true, "smpBlockers": [], "summary": { "tin": "1004****59", "peppolId": "0235:1004****59", "verificationStatus": "True", "linkageStatus": "linked", "aspName": "AZDAN" } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "description": "No tenant, session claimed by another tenant, or management TIN not this tenant's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_SESSION_TENANT_MISMATCH", "message": "This linking session belongs to a different account.", "correlationId": "fta-3c9e…" } } } } }, "404": { "description": "Unknown session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_SESSION_NOT_FOUND", "message": "Unknown or expired linking session.", "correlationId": "fta-3c9e…" } } } } }, "409": { "description": "No linkage for a management entry, environment changed, or the session cannot be claimed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_LINKAGE_NOT_FOUND", "message": "No existing e-Invoicing linkage was found for this account. …", "correlationId": "fta-3c9e…" } } } } }, "410": { "description": "The session expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_SESSION_EXPIRED", "message": "This EmaraTax authorization has expired. …", "correlationId": "fta-3c9e…" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/fta/linkage/select-action": { "post": { "operationId": "postTenantFtaLinkageSelectAction", "summary": "Choose reverify or offboard for an existing linkage", "description": "Records the business operation for a bound session: `reverify` (FTA API-5 action 2) or `offboard` (action 3). The action number is decided server-side; only the word is accepted.\n\nRe-runs the context checks, then refuses: a consumed session (`409 FTA_SESSION_ALREADY_USED`), no existing linkage (`409 FTA_LINKAGE_NOT_FOUND`), `reverify` while an offboarding is still pending with FTA (`409 FTA_OFFBOARDING_IN_PROGRESS`), and a deployment where API-5 cannot run (`503 FTA_CRREG_NOT_READY`). The session's operation moves to `reverify_verification_pending` / `offboard_verification_pending`. Audited as `fta.linkage.action.selected`. `changed: false` when the same action was already selected.\n\nOnly a `tenant_admin` of the tenant may run this step (`403 FTA_ROLE_NOT_PERMITTED` otherwise, audited).\n\n`tenantId` always comes from the session principal; body fields `tenantId`, `environment` and `tin` are ignored (stripped by the schema). Responses carry `Cache-Control: no-store, private, max-age=0`. Errors are `{ error: { code, message, correlationId } }` with no upstream body. Counts against the tenant write limiter (`RATE_LIMIT_WRITE_MAX`, default 60/min per tenant).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "EmaraTax (FTA)" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1, "maxLength": 512 }, "action": { "type": "string", "enum": [ "reverify", "offboard" ] } }, "required": [ "sessionId", "action" ] }, "example": { "sessionId": "kM3v…", "action": "reverify" } } } }, "responses": { "200": { "description": "Operation selected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "correlationId": { "type": "string" }, "action": { "type": "string" }, "operation": { "type": "object", "properties": { "type": { "type": "string" }, "state": { "type": "string" }, "selectedAt": { "type": "string" }, "reasonPresent": { "type": "boolean" }, "acknowledgedAt": { "type": "null" }, "confirmAttempts": { "type": "integer" }, "inFlight": { "type": "boolean" }, "result": { "type": "null" }, "updatedAt": { "type": "string" } } }, "linkage": { "type": "object", "properties": { "tenantId": { "type": "string" }, "environment": { "type": "string" }, "tin": { "type": "string" }, "peppolId": { "type": "string" }, "participantId": { "type": "string" }, "aspName": { "type": "string" }, "claimedAt": { "type": "string" } } }, "changed": { "type": "boolean" } } }, "example": { "ok": true, "correlationId": "fta-3c9e…", "action": "reverify", "operation": { "type": "reverify", "state": "reverify_verification_pending", "selectedAt": "2026-10-24T09:24:10.000Z", "reasonPresent": false, "acknowledgedAt": null, "confirmAttempts": 0, "inFlight": false, "result": null, "updatedAt": "2026-10-24T09:24:10.000Z" }, "linkage": { "tenantId": "tnt_7Q2X…", "environment": "production", "tin": "1004****59", "peppolId": "0235:1004****59", "participantId": "ppt_…", "aspName": "AZDAN", "claimedAt": "2026-10-24T09:23:55.000Z" }, "changed": true } } } }, "400": { "description": "Unsupported action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_LINKAGE_ACTION_INVALID", "message": "Choose either to reverify the linkage or to offboard.", "correlationId": "fta-3c9e…" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "description": "Not a `tenant_admin`, or the session belongs to another tenant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_ROLE_NOT_PERMITTED", "message": "Only an account administrator can manage the e-Invoicing linkage.", "correlationId": "fta-3c9e…" } } } } }, "404": { "description": "Unknown session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_SESSION_NOT_FOUND", "message": "Unknown or expired linking session.", "correlationId": "fta-3c9e…" } } } } }, "409": { "description": "Session used, no linkage, offboarding pending, operation in progress or invalid transition.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_OFFBOARDING_IN_PROGRESS", "message": "An offboarding for this account has not completed with the Federal Tax Authority yet. Complete the offboarding first.", "correlationId": "fta-3c9e…" } } } } }, "410": { "description": "The session expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_SESSION_EXPIRED", "message": "…", "correlationId": "fta-3c9e…" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" }, "503": { "description": "API-5 cannot run on this deployment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_CRREG_NOT_READY", "message": "Linkage changes are temporarily unavailable while the service-provider configuration is being completed.", "correlationId": "fta-3c9e…" } } } } } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/fta/linkage/verify": { "post": { "operationId": "postTenantFtaLinkageVerify", "summary": "Verify the linked taxpayer with FTA (API-4) for reverify or offboard", "description": "Runs FTA API-1 → API-4 with the session's **new** authcode against the tenant's **linked** TIN (no `tin` input). The answer must name exactly that TIN (`409 FTA_TIN_MISMATCH` otherwise). For a linked taxpayer FTA's \"already linked\" answer is accepted only when the email supplied equals the registered admin email FTA verified at onboarding.\n\nRequires a selected operation (`409 FTA_LINKAGE_ACTION_REQUIRED`) in its `*_verification_pending` state; on success the operation moves to `reverify_verified` / `offboard_verified`. Calling again after success returns the stored verification with `reused: true` without calling FTA. Same attempt cap (3) and errors as the onboarding verification. Audited as `fta.reverify.verified` / `fta.offboard.verified` (or `.failed`).\n\nOnly a `tenant_admin` of the tenant may run this step (`403 FTA_ROLE_NOT_PERMITTED` otherwise, audited).\n\n`tenantId` always comes from the session principal; body fields `tenantId`, `environment` and `tin` are ignored (stripped by the schema). Responses carry `Cache-Control: no-store, private, max-age=0`. Errors are `{ error: { code, message, correlationId } }` with no upstream body. Counts against the tenant write limiter (`RATE_LIMIT_WRITE_MAX`, default 60/min per tenant).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "EmaraTax (FTA)" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1, "maxLength": 512 }, "email": { "type": "string", "minLength": 3, "maxLength": 254 }, "mobile": { "type": "string", "maxLength": 32 } }, "required": [ "sessionId", "email" ] }, "example": { "sessionId": "kM3v…", "email": "o***@example.com", "mobile": "+97155****67" } } } }, "responses": { "200": { "description": "Verified for the selected operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "correlationId": { "type": "string" }, "verification": { "type": "object", "properties": { "tin": { "type": "string" }, "email": { "type": "string" }, "mobile": { "type": "string" }, "entityNameEn": { "type": "string" }, "entityNameAr": { "type": "string" }, "vatTrn": { "type": "string" }, "effectiveDate": { "type": "string" }, "legalType": { "type": "string" }, "verificationStatus": { "type": "string" }, "msgCode": { "type": "string" }, "msgDesc": { "type": "string" }, "classification": { "type": "string" } } }, "operation": { "type": "object", "properties": { "type": { "type": "string" }, "state": { "type": "string" }, "selectedAt": { "type": "string" }, "reasonPresent": { "type": "boolean" }, "acknowledgedAt": { "type": "null" }, "confirmAttempts": { "type": "integer" }, "inFlight": { "type": "boolean" }, "result": { "type": "null" }, "updatedAt": { "type": "string" } } }, "reused": { "type": "boolean" } } }, "example": { "ok": true, "correlationId": "fta-3c9e…", "verification": { "tin": "1004****59", "email": "o***@example.com", "mobile": "+97155****67", "entityNameEn": "Example Trading LLC", "entityNameAr": "…", "vatTrn": "1004****59003", "effectiveDate": "2026-01-01", "legalType": "LLC", "verificationStatus": "True", "msgCode": "…", "msgDesc": "…", "classification": "existing_linkage_verified" }, "operation": { "type": "reverify", "state": "reverify_verified", "selectedAt": "2026-10-24T09:24:10.000Z", "reasonPresent": false, "acknowledgedAt": null, "confirmAttempts": 0, "inFlight": false, "result": null, "updatedAt": "2026-10-24T09:24:10.000Z" }, "reused": false } } } }, "400": { "description": "Field validation failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "fields": { "type": "object", "properties": { "email": { "type": "string" } } }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_INPUT_INVALID", "message": "Please correct the highlighted fields.", "fields": { "email": "Enter the registered admin email address." }, "correlationId": "fta-3c9e…" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "description": "Not a `tenant_admin`, or the session belongs to another tenant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_ROLE_NOT_PERMITTED", "message": "Only an account administrator can manage the e-Invoicing linkage.", "correlationId": "fta-3c9e…" } } } } }, "404": { "description": "Unknown session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_SESSION_NOT_FOUND", "message": "Unknown or expired linking session.", "correlationId": "fta-3c9e…" } } } } }, "409": { "description": "No action selected, session used/unclaimed, invalid transition, or FTA verified a different TIN.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_LINKAGE_ACTION_REQUIRED", "message": "Choose reverify or offboard first.", "correlationId": "fta-3c9e…" } } } } }, "410": { "description": "The session expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_SESSION_EXPIRED", "message": "…", "correlationId": "fta-3c9e…" } } } } }, "422": { "description": "FTA did not verify the taxpayer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "msgCode": { "type": "string" }, "msgDesc": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_VERIFICATION_FAILED", "message": "…", "msgCode": "…", "msgDesc": "…", "correlationId": "fta-3c9e…" } } } } }, "429": { "description": "Verification attempts for this session are spent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_TOO_MANY_ATTEMPTS", "message": "…", "correlationId": "fta-3c9e…" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" }, "502": { "description": "An FTA gateway call failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_UPSTREAM_ERROR", "message": "…", "correlationId": "fta-3c9e…" } } } } } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/fta/linkage/reverify/confirm": { "post": { "operationId": "postTenantFtaLinkageReverifyConfirm", "summary": "Confirm reverification (FTA API-5 action 2)", "description": "Requires `acknowledged: true`, a non-empty `reason` (whitespace-collapsed, max 500 characters), a verified reverify operation, and the TIN chain profile TIN = bound TIN = FTA-verified TIN. Then calls FTA API-5 `crregupdate` action 2 and records the outcome on the durable profile.\n\n- FTA confirmed → `outcome: \"reverified\"`, `completed: true`; session spent; tenant lifecycle records the reverification.\n- Sent but unconfirmed → `200` with `outcome: \"unconfirmed\"`, `completed: false`.\n- Failed → `502` with `outcome: \"failed\"` and the `crreg` view in the body; when `retryable` the session stays verified and the same request may be repeated, otherwise the session is spent. The linkage is unchanged either way.\n\nRepeating a finished confirmation returns the recorded result. Audited (`fta.reverify.completed` / `.failed`).\n\nOnly a `tenant_admin` of the tenant may run this step (`403 FTA_ROLE_NOT_PERMITTED` otherwise, audited).\n\n`tenantId` always comes from the session principal; body fields `tenantId`, `environment` and `tin` are ignored (stripped by the schema). Responses carry `Cache-Control: no-store, private, max-age=0`. Errors are `{ error: { code, message, correlationId } }` with no upstream body. Counts against the tenant write limiter (`RATE_LIMIT_WRITE_MAX`, default 60/min per tenant).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "EmaraTax (FTA)" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1, "maxLength": 512 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "acknowledged": { "const": true } }, "required": [ "sessionId", "reason", "acknowledged" ] }, "example": { "sessionId": "kM3v…", "reason": "Annual reverification requested by EmaraTax", "acknowledged": true } } } }, "responses": { "200": { "description": "Reverified (or sent and unconfirmed — see `outcome`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "correlationId": { "type": "string" }, "requestId": { "type": "string" }, "outcome": { "type": "string" }, "completed": { "type": "boolean" }, "crreg": { "type": "object", "properties": { "status": { "type": "string" }, "action": { "type": "integer" }, "msgCode": { "type": "string" }, "errorCode": { "type": "null" }, "onboardingStatus": { "type": "string" }, "verificationStatus": { "type": "string" }, "recordUpdateTimestamp": { "type": "string" }, "retryable": { "type": "boolean" }, "diagnosticId": { "type": "string" } } }, "summary": { "type": "object", "properties": { "tin": { "type": "string" }, "peppolId": { "type": "string" }, "verificationStatus": { "type": "string" }, "linkageStatus": { "type": "string" }, "aspName": { "type": "string" } } }, "profileRecorded": { "type": "boolean" } } }, "example": { "ok": true, "correlationId": "fta-3c9e…", "requestId": "far_…", "outcome": "reverified", "completed": true, "crreg": { "status": "ok", "action": 2, "msgCode": "…", "errorCode": null, "onboardingStatus": "Active", "verificationStatus": "True", "recordUpdateTimestamp": "2026-10-24T09:41:07Z", "retryable": false, "diagnosticId": "fxd_…" }, "summary": { "tin": "1004****59", "peppolId": "0235:1004****59", "verificationStatus": "True", "linkageStatus": "linked", "aspName": "AZDAN" }, "profileRecorded": true } } } }, "400": { "description": "Reason missing or acknowledgement absent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_REASON_REQUIRED", "message": "A reason is required.", "correlationId": "fta-3c9e…" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "description": "Not a `tenant_admin`, or the session belongs to another tenant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_ROLE_NOT_PERMITTED", "message": "Only an account administrator can manage the e-Invoicing linkage.", "correlationId": "fta-3c9e…" } } } } }, "404": { "description": "Unknown session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_SESSION_NOT_FOUND", "message": "Unknown or expired linking session.", "correlationId": "fta-3c9e…" } } } } }, "409": { "description": "Not verified, wrong operation, in progress, or TIN chain mismatch.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_OPERATION_IN_PROGRESS", "message": "This request is already being processed. Please wait for it to finish.", "correlationId": "fta-3c9e…" } } } } }, "410": { "description": "The session expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_SESSION_EXPIRED", "message": "…", "correlationId": "fta-3c9e…" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" }, "502": { "description": "FTA did not accept or could not be reached. Body: the error plus `outcome` and `crreg`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" }, "retryable": { "type": "boolean" } } }, "outcome": { "type": "string" }, "crreg": { "type": "object", "properties": { "status": { "type": "string" }, "action": { "type": "integer" }, "msgCode": { "type": "string" }, "errorCode": { "type": "null" }, "onboardingStatus": { "type": "null" }, "verificationStatus": { "type": "string" }, "recordUpdateTimestamp": { "type": "string" }, "retryable": { "type": "boolean" }, "diagnosticId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_CENTRAL_REGISTRATION_FAILED", "message": "The Federal Tax Authority could not be reached. Your linkage is unchanged — please try again.", "correlationId": "fta-3c9e…", "retryable": true }, "outcome": "failed", "crreg": { "status": "failed", "action": 2, "msgCode": "…", "errorCode": null, "onboardingStatus": null, "verificationStatus": "True", "recordUpdateTimestamp": "2026-10-24T09:41:07Z", "retryable": true, "diagnosticId": "fxd_…" } } } } } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/fta/linkage/offboard/confirm": { "post": { "operationId": "postTenantFtaLinkageOffboardConfirm", "summary": "Confirm offboarding: remove from Peppol, then delink in EmaraTax", "description": "Same preconditions as reverify confirmation (acknowledgement, reason, verified offboard operation, TIN chain). Then, in the order the FTA End-User Process requires:\n\n1. **Peppol removal** — (a) the participant is offboarded from the AZDAN SMP (one `DELETE` with `delete-in-sml=true`; the platform reads back a 404; already absent counts as success) and the outcome is persisted; (b) the tenant's participant row `0235:` in this environment is deactivated (never hard-deleted). If (a) fails nothing local changes and nothing is sent to FTA; if (b) fails a retry repeats only (b). Either failure answers `502` with `participantRemoval`/`smpUnpublish` in the body.\n2. **FTA API-5** `crregupdate` action 3.\n\n- FTA confirmed → `outcome: \"offboarded\"`, `completed: true`; session spent; the tenant lifecycle hook runs (offboarding the tenant's last taxpayer suspends the account and revokes its sessions) and the `fta_offboarded` email is queued.\n- FTA did not confirm → **partial state** `200` with `outcome: \"fta_delink_pending\"`, `completed: false`; the participant stays deactivated and the profile records the stage. When `retryable` the same session may retry step 2 only; otherwise an operator follow-up and the `fta_offboard_pending` email.\n\nIf FTA already confirmed a delink for this TIN that the profile missed, the confirmation is recovered from diagnostics without calling FTA again. Audited (`fta.offboard.*`).\n\nOnly a `tenant_admin` of the tenant may run this step (`403 FTA_ROLE_NOT_PERMITTED` otherwise, audited).\n\n`tenantId` always comes from the session principal; body fields `tenantId`, `environment` and `tin` are ignored (stripped by the schema). Responses carry `Cache-Control: no-store, private, max-age=0`. Errors are `{ error: { code, message, correlationId } }` with no upstream body. Counts against the tenant write limiter (`RATE_LIMIT_WRITE_MAX`, default 60/min per tenant).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "EmaraTax (FTA)" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1, "maxLength": 512 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "acknowledged": { "const": true } }, "required": [ "sessionId", "reason", "acknowledged" ] }, "example": { "sessionId": "kM3v…", "reason": "Moving to another accredited service provider", "acknowledged": true } } } }, "responses": { "200": { "description": "Offboarded, or the partial `fta_delink_pending` state — check `completed`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "correlationId": { "type": "string" }, "requestId": { "type": "string" }, "outcome": { "type": "string" }, "completed": { "type": "boolean" }, "participantRemoval": { "type": "object", "properties": { "status": { "type": "string" }, "participantId": { "type": "string" }, "peppolId": { "type": "string" }, "previousStatus": { "type": "string" }, "errorCode": { "type": "null" }, "at": { "type": "string" } } }, "smpUnpublish": { "type": "object", "properties": { "status": { "type": "string" }, "at": { "type": "string" }, "serviceGroupId": { "type": "string" }, "endpoint": { "type": "string" }, "steps": { "type": "null" }, "verifiedAbsent": { "type": "boolean" }, "errorCode": { "type": "null" } } }, "crreg": { "type": "object", "properties": { "status": { "type": "string" }, "action": { "type": "integer" }, "msgCode": { "type": "string" }, "errorCode": { "type": "null" }, "onboardingStatus": { "type": "string" }, "verificationStatus": { "type": "string" }, "recordUpdateTimestamp": { "type": "string" }, "retryable": { "type": "boolean" }, "diagnosticId": { "type": "string" } } }, "summary": { "type": "object", "properties": { "tin": { "type": "string" }, "peppolId": { "type": "string" }, "verificationStatus": { "type": "string" }, "linkageStatus": { "type": "string" }, "aspName": { "type": "string" } } }, "profileRecorded": { "type": "boolean" } } }, "example": { "ok": true, "correlationId": "fta-3c9e…", "requestId": "far_…", "outcome": "offboarded", "completed": true, "participantRemoval": { "status": "removed", "participantId": "ppt_…", "peppolId": "0235:1004****59", "previousStatus": "active", "errorCode": null, "at": "2026-10-24T09:44:02.000Z" }, "smpUnpublish": { "status": "unpublished", "at": "2026-10-24T09:44:01.000Z", "serviceGroupId": "iso6523-actorid-upis::0235:1004****59", "endpoint": "https://smp.example.net", "steps": null, "verifiedAbsent": true, "errorCode": null }, "crreg": { "status": "ok", "action": 3, "msgCode": "…", "errorCode": null, "onboardingStatus": "Inactive", "verificationStatus": "True", "recordUpdateTimestamp": "2026-10-24T09:41:07Z", "retryable": false, "diagnosticId": "fxd_…" }, "summary": { "tin": "1004****59", "peppolId": "0235:1004****59", "verificationStatus": "True", "linkageStatus": "offboarded", "aspName": "AZDAN" }, "profileRecorded": true } } } }, "400": { "description": "Reason missing or acknowledgement absent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_REASON_REQUIRED", "message": "A reason is required.", "correlationId": "fta-3c9e…" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "description": "Not a `tenant_admin`, or the session belongs to another tenant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_ROLE_NOT_PERMITTED", "message": "Only an account administrator can manage the e-Invoicing linkage.", "correlationId": "fta-3c9e…" } } } } }, "404": { "description": "Unknown session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_SESSION_NOT_FOUND", "message": "Unknown or expired linking session.", "correlationId": "fta-3c9e…" } } } } }, "409": { "description": "Not verified, wrong operation, in progress, or TIN chain mismatch.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_OPERATION_IN_PROGRESS", "message": "This request is already being processed. Please wait for it to finish.", "correlationId": "fta-3c9e…" } } } } }, "410": { "description": "The session expired.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" } } } } }, "example": { "error": { "code": "FTA_SESSION_EXPIRED", "message": "…", "correlationId": "fta-3c9e…" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" }, "502": { "description": "The Peppol removal step failed; nothing was sent to FTA. Body: the error plus `outcome` and `participantRemoval`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "correlationId": { "type": "string" }, "retryable": { "type": "boolean" } } }, "outcome": { "type": "string" }, "participantRemoval": { "type": "object", "properties": { "status": { "type": "string" }, "participantId": { "type": "string" }, "peppolId": { "type": "string" }, "previousStatus": { "type": "null" }, "errorCode": { "type": "null" }, "at": { "type": "null" } } } } }, "example": { "error": { "code": "FTA_PEPPOL_REMOVAL_FAILED", "message": "…", "correlationId": "fta-3c9e…", "retryable": true }, "outcome": "failed", "participantRemoval": { "status": "not_attempted", "participantId": "ppt_…", "peppolId": "0235:1004****59", "previousStatus": null, "errorCode": null, "at": null } } } } } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/fta/profile": { "get": { "operationId": "getTenantFtaProfile", "summary": "Get the tenant's durable EmaraTax profiles", "description": "Read-only FTA / EmaraTax status of the signed-in tenant: one profile per (environment, TIN), sorted by environment then TIN. Each carries the FTA-verified entity facts, ASP link, Peppol participant, central-registry (API-5) state, offboarding/reverification state and operation history, plus derived `overallStatus`, `nextAction`, `timeline` and `configurationHealthy` (FTA credentials configured). No credentials, session or authcode. `Cache-Control: no-store`. The example is abridged.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "EmaraTax (FTA)" ], "responses": { "200": { "description": "Profiles (possibly empty).", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "profiles": { "type": "array", "items": { "type": "object", "properties": { "tenantId": { "type": "string" }, "environment": { "type": "string" }, "tin": { "type": "string" }, "verification": { "type": "object", "properties": { "status": { "type": "string" }, "tin": { "type": "string" }, "vatTrn": { "type": "string" }, "entityNameEn": { "type": "string" }, "entityNameAr": { "type": "string" }, "legalType": { "type": "string" }, "effectiveDate": { "type": "string" }, "verificationStatus": { "type": "string" }, "registeredAdminEmail": { "type": "string" }, "mobile": { "type": "string" }, "verifiedAt": { "type": "string" } } }, "aspLink": { "type": "object", "properties": { "status": { "type": "string" }, "linkedAt": { "type": "string" }, "offboardedAt": { "type": "null" } } }, "peppol": { "type": "object", "properties": { "status": { "type": "string" }, "participantId": { "type": "string" }, "peppolId": { "type": "string" }, "participantCreatedAt": { "type": "string" } } }, "centralRegistry": { "type": "object", "properties": { "status": { "type": "string" }, "onboardingStatus": { "type": "string" }, "lastAction": { "type": "integer" }, "activatedAt": { "type": "string" } } }, "overallStatus": { "type": "string" }, "nextAction": { "type": "null" }, "configurationHealthy": { "type": "boolean" } } } } } }, "example": { "ok": true, "profiles": [ { "tenantId": "tnt_7Q2X…", "environment": "production", "tin": "1004****59", "verification": { "status": "verified", "tin": "1004****59", "vatTrn": "1004****59003", "entityNameEn": "Example Trading LLC", "entityNameAr": "…", "legalType": "LLC", "effectiveDate": "2026-01-01", "verificationStatus": "True", "registeredAdminEmail": "o***@example.com", "mobile": "+97155****67", "verifiedAt": "2026-09-02T10:09:12.000Z" }, "aspLink": { "status": "linked", "linkedAt": "2026-09-02T10:11:00.000Z", "offboardedAt": null }, "peppol": { "status": "active", "participantId": "ppt_…", "peppolId": "0235:1004****59", "participantCreatedAt": "2026-09-02T10:10:40.000Z" }, "centralRegistry": { "status": "ok", "onboardingStatus": "Active", "lastAction": 1, "activatedAt": "2026-09-02T10:11:00.000Z" }, "overallStatus": "linked", "nextAction": null, "configurationHealthy": true } ] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/ap-transactions": { "get": { "operationId": "getTenantApTransactions", "summary": "List the tenant's access point transactions", "description": "The access point's own transaction log for the caller's tenant: inbound rows whose receiver and outbound rows whose sender is one of the tenant's active Peppol participants (tenant_user: only participants on their subsidiary/participant allow-lists, re-read from the database on each call). Live and archived rows, merged newest first, with the same filters and page-number pagination as the admin list. Object-storage coordinates and the spool path are removed: `storage` keeps only `provider`, `fileType`, `sizeBytes`, `legacy`, and `documentPath` is `null`.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Transactions" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "peppolId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } } ], "responses": { "200": { "description": "A page of AP rows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "direction": { "type": "string" }, "tenantId": { "type": "string" }, "sender": { "type": "string" }, "receiver": { "type": "string" }, "documentType": { "type": "string" }, "processId": { "type": "string" }, "status": { "type": "string" }, "mlsType": { "type": "string" }, "mlsTo": { "type": "string" }, "mlsResponseCode": { "type": "string" }, "mlsOutboundTransactionId": { "type": "string" }, "tddTransactionId": { "type": "string" }, "tddSbdhInstanceId": { "type": "string" }, "tddStatus": { "type": "string" }, "tddCreatedAt": { "type": "string" }, "tddLastError": { "type": "null" }, "receivedAt": { "type": "string" }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" }, "errorDetails": { "type": "null" }, "documentPath": { "type": "null" }, "documentSize": { "type": "integer" }, "as4MessageId": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "correlationId": { "type": "null" }, "storage": { "type": "object", "properties": { "provider": { "type": "string" }, "fileType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "legacy": { "type": "boolean" } } }, "archived": { "type": "boolean" }, "documentKind": { "type": "string" }, "statusDetail": { "type": "object", "properties": { "documentKind": { "type": "string" }, "overall": { "type": "string" }, "processing": { "type": "object", "properties": { "platformStatus": { "type": "null" }, "apStatus": { "type": "string" }, "source": { "type": "string" }, "createdAt": { "type": "string" }, "failureStage": { "type": "null" } } }, "validation": { "type": "object", "properties": { "state": { "type": "string" }, "engine": { "type": "string" }, "at": { "type": "string" }, "warnings": { "type": "integer" }, "error": { "type": "null" } } }, "delivery": { "type": "object", "properties": { "state": { "type": "string" }, "apStatus": { "type": "string" }, "platformStatus": { "type": "null" }, "attempts": { "type": "null" }, "lastAttemptAt": { "type": "null" }, "completedAt": { "type": "string" }, "failedAt": { "type": "null" }, "errorCode": { "type": "null" }, "error": { "type": "null" } } }, "mls": { "type": "object", "properties": { "role": { "type": "string" }, "state": { "type": "string" }, "code": { "type": "string" }, "raw": { "type": "string" }, "at": { "type": "null" }, "mlsId": { "type": "null" }, "errorCode": { "type": "null" }, "errorMessage": { "type": "null" }, "policy": { "type": "string" } } }, "reporting": { "type": "object", "properties": { "state": { "type": "string" }, "raw": { "type": "string" }, "at": { "type": "string" }, "error": { "type": "null" }, "ftaResponse": { "type": "null" } } } } } } } }, "page": { "type": "object", "properties": { "number": { "type": "integer" }, "size": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } }, "example": { "items": [ { "id": "6716f0aa…41d2", "source": "inbound_transactions", "direction": "inbound", "tenantId": "tnt_7Q2X…", "sender": "0235:1004****59", "receiver": "0235:1007****21", "documentType": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "status": "forwarded", "mlsType": "always", "mlsTo": "0235:1004****59", "mlsResponseCode": "AP", "mlsOutboundTransactionId": "6716f0b9…08ce", "tddTransactionId": "6716f0c4…5a17", "tddSbdhInstanceId": "3f1c9e2a-…", "tddStatus": "sent", "tddCreatedAt": "2026-10-21T09:14:41.000Z", "tddLastError": null, "receivedAt": "2026-10-21T09:14:03.000Z", "createdAt": "2026-10-21T09:14:03.000Z", "completedAt": "2026-10-21T09:14:41.000Z", "errorDetails": null, "documentPath": null, "documentSize": 18342, "as4MessageId": "a91f…@azdan-ap", "sbdhInstanceId": "b7d2e0f4-…", "correlationId": null, "storage": { "provider": "oci", "fileType": "payload", "sizeBytes": 18342, "legacy": false }, "archived": false, "documentKind": "invoice", "statusDetail": { "documentKind": "invoice", "overall": "delivered", "processing": { "platformStatus": null, "apStatus": "forwarded", "source": "ap", "createdAt": "2026-10-21T09:14:03.000Z", "failureStage": null }, "validation": { "state": "passed", "engine": "ap_core", "at": "2026-10-21T09:14:03.000Z", "warnings": 0, "error": null }, "delivery": { "state": "delivered", "apStatus": "forwarded", "platformStatus": null, "attempts": null, "lastAttemptAt": null, "completedAt": "2026-10-21T09:14:41.000Z", "failedAt": null, "errorCode": null, "error": null }, "mls": { "role": "sent", "state": "accepted", "code": "AP", "raw": "AP", "at": null, "mlsId": null, "errorCode": null, "errorMessage": null, "policy": "always" }, "reporting": { "state": "reported", "raw": "sent", "at": "2026-10-21T09:14:41.000Z", "error": null, "ftaResponse": null } } }, { "id": "6716e8d1…77b3", "source": "outbound_transactions", "direction": "outbound", "tenantId": "tnt_7Q2X…", "sender": "0235:1007****21", "receiver": "0235:1004****59", "documentType": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "status": "sent", "mlsStatus": "received_ap", "mlsReceivedAt": "2026-10-21T09:14:41.000Z", "mlsId": "mls_…", "mlsInboundTransactionId": null, "mlsType": "always", "mlsErrorCode": null, "mlsErrorMessage": null, "mlsAs4MessageId": "c03e…@ap.example", "mlsRefToMessageId": "e81a…@azdan-ap", "mlsLastAttemptAt": "2026-10-21T09:14:41.000Z", "mlsAttemptCount": 1, "parentTransactionId": null, "parentSbdhInstanceId": null, "parentAs4MessageId": null, "parentDocumentType": null, "generatedFrom": null, "tddTypeCode": null, "precedingTddTransactionId": null, "precedingTddSbdhInstanceId": null, "supersededByTransactionId": null, "tddReason": null, "tddFollowUpStatus": null, "tddFollowUpError": null, "receivedAt": "2026-10-21T09:14:03.000Z", "createdAt": "2026-10-21T09:14:03.000Z", "completedAt": "2026-10-21T09:14:41.000Z", "errorDetails": null, "sendingError": null, "as4ErrorCode": null, "as4ErrorDetail": null, "retryCount": 1, "lastAttemptAt": "2026-10-21T09:14:03.000Z", "failureCategory": null, "documentPath": null, "documentSize": 21004, "as4MessageId": "e81a…@azdan-ap", "sbdhInstanceId": "5aa0c7e1-…", "correlationId": "txn_8F2K…", "storage": { "provider": "oci", "fileType": "sbdh", "sizeBytes": 21004, "legacy": false }, "archived": false, "documentKind": "invoice", "statusDetail": { "documentKind": "invoice", "overall": "accepted", "processing": { "platformStatus": null, "apStatus": "sent", "source": "ap", "createdAt": "2026-10-21T09:14:03.000Z", "failureStage": null }, "validation": { "state": "passed", "engine": "ap_core", "at": "2026-10-21T09:14:03.000Z", "warnings": 0, "error": null }, "delivery": { "state": "delivered", "apStatus": "sent", "platformStatus": null, "attempts": 1, "lastAttemptAt": "2026-10-21T09:14:03.000Z", "completedAt": "2026-10-21T09:14:41.000Z", "failedAt": null, "errorCode": null, "error": null }, "mls": { "role": "received", "state": "accepted", "code": "AP", "raw": "received_ap", "at": "2026-10-21T09:14:41.000Z", "mlsId": "mls_…", "errorCode": null, "errorMessage": null, "policy": "always" }, "reporting": { "state": "unknown" } } } ], "page": { "number": 1, "size": 25, "total": 2, "totalPages": 1 } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/ap-transactions/{id}/tdd": { "get": { "operationId": "getTenantApTransactionsByIdTdd", "summary": "Get the UAE tax data document (TDD) of a transaction", "description": "Resolves the TDD the access point generated for a transaction. `{id}` may be a platform transaction id or an AP inbound/outbound id. For an outbound invoice with several TDDs (Submit, then Withdraw/Resubmit) the current one is returned. Ownership is checked against the tenant's Peppol participants (not the tenant_user allow-lists). Side effect: if the TDD XML is not yet registered, it is uploaded to object storage and a `transaction_files` row is created before responding.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Transactions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "TDD metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tdd": { "type": "object", "properties": { "fileId": { "type": "string" }, "transactionId": { "type": "string" }, "parentTransactionId": { "type": "string" }, "apTddTransactionId": { "type": "string" }, "status": { "type": "string" }, "documentTypeId": { "type": "string" }, "processId": { "type": "string" }, "generatedAt": { "type": "string" }, "sha256": { "type": "string" }, "sizeBytes": { "type": "integer" }, "contentType": { "type": "string" }, "source": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "apCoreMessageId": { "type": "string" }, "tddDownloadUrl": { "type": "string" } } } } }, "example": { "tdd": { "fileId": "fil_5Rk…", "transactionId": "txn_8F2K…", "parentTransactionId": "txn_8F2K…", "apTddTransactionId": "6716f0c4…5a17", "status": "sent", "documentTypeId": "urn:peppol:edec:taxdata:…", "processId": "urn:peppol:edec:taxdata:…", "generatedAt": "2026-10-21T09:14:41.000Z", "sha256": "e2b7…9a01", "sizeBytes": 6120, "contentType": "application/xml", "source": "ap_core_generated_tdd", "sbdhInstanceId": "0d4f8b11-…", "apCoreMessageId": "f7c2…@azdan-ap", "tddDownloadUrl": "/api/tenant/ap-transactions/txn_8F2K…/tdd/download" } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/ap-transactions/{id}/tdd/download": { "get": { "operationId": "getTenantApTransactionsByIdTddDownload", "summary": "Get a signed download URL for a transaction's TDD", "description": "Same resolution and side effects as `GET …/{id}/tdd`, then creates a read-only OCI pre-authenticated request (PAR) for the TDD XML and returns its URL. The URL always expires after 15 minutes: `ttlSeconds` is accepted but ignored by the signer. Unlike the metadata route, the TDD fields are returned flat, not under `tdd`.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Transactions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "ttlSeconds", "in": "query", "description": "Accepted but ignored: every link is valid for 900 seconds.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "TDD metadata and a signed URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "fileId": { "type": "string" }, "transactionId": { "type": "string" }, "parentTransactionId": { "type": "string" }, "apTddTransactionId": { "type": "string" }, "status": { "type": "string" }, "documentTypeId": { "type": "string" }, "processId": { "type": "string" }, "generatedAt": { "type": "string" }, "sha256": { "type": "string" }, "sizeBytes": { "type": "integer" }, "contentType": { "type": "string" }, "source": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "apCoreMessageId": { "type": "string" }, "tddDownloadUrl": { "type": "string" }, "downloadUrl": { "type": "string" }, "ttlSeconds": { "type": "integer" } } }, "example": { "fileId": "fil_5Rk…", "transactionId": "txn_8F2K…", "parentTransactionId": "txn_8F2K…", "apTddTransactionId": "6716f0c4…5a17", "status": "sent", "documentTypeId": "urn:peppol:edec:taxdata:…", "processId": "urn:peppol:edec:taxdata:…", "generatedAt": "2026-10-21T09:14:41.000Z", "sha256": "e2b7…9a01", "sizeBytes": 6120, "contentType": "application/xml", "source": "ap_core_generated_tdd", "sbdhInstanceId": "0d4f8b11-…", "apCoreMessageId": "f7c2…@azdan-ap", "tddDownloadUrl": "/api/tenant/ap-transactions/txn_8F2K…/tdd/download", "downloadUrl": "https://objectstorage.me-dubai-1.oraclecloud.com/p/••••/n/axq…/b/azdan-einvoice-…/o/…/tdd.xml", "ttlSeconds": 900 } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" }, "502": { "$ref": "#/components/responses/ErrBadGateway" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/ap-transactions/{id}": { "get": { "operationId": "getTenantApTransactionsById", "summary": "Get one of the tenant's access point transactions", "description": "Returns one AP row by AP id from the collection named in `source`, only when its owning participant (receiver for inbound, sender for outbound) is visible to the caller; otherwise 404. Storage coordinates and the spool path are removed as in the list.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Transactions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "inbound_transactions", "outbound_transactions" ] } } ], "responses": { "200": { "description": "The AP row.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "direction": { "type": "string" }, "tenantId": { "type": "string" }, "sender": { "type": "string" }, "receiver": { "type": "string" }, "documentType": { "type": "string" }, "processId": { "type": "string" }, "status": { "type": "string" }, "mlsStatus": { "type": "string" }, "mlsReceivedAt": { "type": "string" }, "mlsId": { "type": "string" }, "mlsInboundTransactionId": { "type": "null" }, "mlsType": { "type": "string" }, "mlsErrorCode": { "type": "null" }, "mlsErrorMessage": { "type": "null" }, "mlsAs4MessageId": { "type": "string" }, "mlsRefToMessageId": { "type": "string" }, "mlsLastAttemptAt": { "type": "string" }, "mlsAttemptCount": { "type": "integer" }, "parentTransactionId": { "type": "null" }, "parentSbdhInstanceId": { "type": "null" }, "parentAs4MessageId": { "type": "null" }, "parentDocumentType": { "type": "null" }, "generatedFrom": { "type": "null" }, "tddTypeCode": { "type": "null" }, "precedingTddTransactionId": { "type": "null" }, "precedingTddSbdhInstanceId": { "type": "null" }, "supersededByTransactionId": { "type": "null" }, "tddReason": { "type": "null" }, "tddFollowUpStatus": { "type": "null" }, "tddFollowUpError": { "type": "null" }, "receivedAt": { "type": "string" }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" }, "errorDetails": { "type": "null" }, "sendingError": { "type": "null" }, "as4ErrorCode": { "type": "null" }, "as4ErrorDetail": { "type": "null" }, "retryCount": { "type": "integer" }, "lastAttemptAt": { "type": "string" }, "failureCategory": { "type": "null" }, "documentPath": { "type": "null" }, "documentSize": { "type": "integer" }, "as4MessageId": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "correlationId": { "type": "string" }, "storage": { "type": "object", "properties": { "provider": { "type": "string" }, "fileType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "legacy": { "type": "boolean" } } }, "archived": { "type": "boolean" }, "documentKind": { "type": "string" }, "statusDetail": { "type": "object", "properties": { "documentKind": { "type": "string" }, "overall": { "type": "string" }, "processing": { "type": "object", "properties": { "platformStatus": { "type": "null" }, "apStatus": { "type": "string" }, "source": { "type": "string" }, "createdAt": { "type": "string" }, "failureStage": { "type": "null" } } }, "validation": { "type": "object", "properties": { "state": { "type": "string" }, "engine": { "type": "string" }, "at": { "type": "string" }, "warnings": { "type": "integer" }, "error": { "type": "null" } } }, "delivery": { "type": "object", "properties": { "state": { "type": "string" }, "apStatus": { "type": "string" }, "platformStatus": { "type": "null" }, "attempts": { "type": "integer" }, "lastAttemptAt": { "type": "string" }, "completedAt": { "type": "string" }, "failedAt": { "type": "null" }, "errorCode": { "type": "null" }, "error": { "type": "null" } } }, "mls": { "type": "object", "properties": { "role": { "type": "string" }, "state": { "type": "string" }, "code": { "type": "string" }, "raw": { "type": "string" }, "at": { "type": "string" }, "mlsId": { "type": "string" }, "errorCode": { "type": "null" }, "errorMessage": { "type": "null" }, "policy": { "type": "string" } } }, "reporting": { "type": "object", "properties": { "state": { "type": "string" } } } } } } }, "example": { "id": "6716e8d1…77b3", "source": "outbound_transactions", "direction": "outbound", "tenantId": "tnt_7Q2X…", "sender": "0235:1007****21", "receiver": "0235:1004****59", "documentType": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "status": "sent", "mlsStatus": "received_ap", "mlsReceivedAt": "2026-10-21T09:14:41.000Z", "mlsId": "mls_…", "mlsInboundTransactionId": null, "mlsType": "always", "mlsErrorCode": null, "mlsErrorMessage": null, "mlsAs4MessageId": "c03e…@ap.example", "mlsRefToMessageId": "e81a…@azdan-ap", "mlsLastAttemptAt": "2026-10-21T09:14:41.000Z", "mlsAttemptCount": 1, "parentTransactionId": null, "parentSbdhInstanceId": null, "parentAs4MessageId": null, "parentDocumentType": null, "generatedFrom": null, "tddTypeCode": null, "precedingTddTransactionId": null, "precedingTddSbdhInstanceId": null, "supersededByTransactionId": null, "tddReason": null, "tddFollowUpStatus": null, "tddFollowUpError": null, "receivedAt": "2026-10-21T09:14:03.000Z", "createdAt": "2026-10-21T09:14:03.000Z", "completedAt": "2026-10-21T09:14:41.000Z", "errorDetails": null, "sendingError": null, "as4ErrorCode": null, "as4ErrorDetail": null, "retryCount": 1, "lastAttemptAt": "2026-10-21T09:14:03.000Z", "failureCategory": null, "documentPath": null, "documentSize": 21004, "as4MessageId": "e81a…@azdan-ap", "sbdhInstanceId": "5aa0c7e1-…", "correlationId": "txn_8F2K…", "storage": { "provider": "oci", "fileType": "sbdh", "sizeBytes": 21004, "legacy": false }, "archived": false, "documentKind": "invoice", "statusDetail": { "documentKind": "invoice", "overall": "accepted", "processing": { "platformStatus": null, "apStatus": "sent", "source": "ap", "createdAt": "2026-10-21T09:14:03.000Z", "failureStage": null }, "validation": { "state": "passed", "engine": "ap_core", "at": "2026-10-21T09:14:03.000Z", "warnings": 0, "error": null }, "delivery": { "state": "delivered", "apStatus": "sent", "platformStatus": null, "attempts": 1, "lastAttemptAt": "2026-10-21T09:14:03.000Z", "completedAt": "2026-10-21T09:14:41.000Z", "failedAt": null, "errorCode": null, "error": null }, "mls": { "role": "received", "state": "accepted", "code": "AP", "raw": "received_ap", "at": "2026-10-21T09:14:41.000Z", "mlsId": "mls_…", "errorCode": null, "errorMessage": null, "policy": "always" }, "reporting": { "state": "unknown" } } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/invoices/templates/{kind}": { "get": { "operationId": "getTenantInvoicesTemplatesByKind", "summary": "Download an invoice starter template", "description": "Static documentation artifacts — no tenant data is read. `kind=xml` returns a complete PINT-AE sample (`application/xml`, as an attachment; `documentType=creditNote` returns a credit note instead of an invoice), `kind=csv` returns the CSV import template (`text/csv`, one row per invoice line) and `kind=spec` returns the CSV column contract as JSON (shown below). Any other `kind` answers 400 `UNKNOWN_TEMPLATE`.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Invoice sending" ], "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "documentType", "in": "query", "description": "For `kind=xml` only: which sample to build.", "schema": { "type": "string", "enum": [ "invoice", "creditNote" ], "default": "invoice" } } ], "responses": { "200": { "description": "The template. JSON for `spec`; an XML or CSV file download for `xml` / `csv`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" }, "scope": { "type": "string" }, "example": { "type": "string" } } } }, "rules": { "type": "array", "items": { "type": "string" } } } }, "example": { "columns": [ { "name": "invoice_number", "required": true, "scope": "invoice", "example": "INV-2026-0001" }, { "name": "customer_peppol_id", "required": true, "scope": "invoice", "example": "0235:1000000002" } ], "rules": [ "One row per invoice line.", "Rows that share the same invoice_number belong to the same invoice; the invoice-level columns are read from that group's first row." ] } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/invoices/validate": { "post": { "operationId": "postTenantInvoicesValidate", "summary": "Validate an invoice without sending it", "description": "Dry-run of the same validation pipeline as `POST /api/integrations/peppol/validate` (inputs `xml`, `json` or `mapped`), authenticated with the user's session instead of an API key. Nothing is persisted and no receiver is contacted. A `tenant_user` may only name a `senderPeppolId` on their allow-list; otherwise 403 `SENDER_NOT_IN_USER_SCOPE` and a `denied` audit row. The sender must also belong to the tenant (403 `SENDER_NOT_OWNED`). A document that fails validation answers 400 with `valid: false` and the rule details.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Invoice sending" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "inputType": { "const": "xml", "type": "string" }, "environment": { "type": "string", "enum": [ "test", "production" ], "default": "test" }, "documentType": { "type": "string", "enum": [ "invoice", "creditNote" ] }, "senderPeppolId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[0-9]{4}:.+$" }, "receiverPeppolId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[0-9]{4}:.+$" }, "xml": { "type": "string", "minLength": 20, "maxLength": 15728640 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 120 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 120 }, "forceResubmit": { "type": "boolean" } }, "required": [ "inputType", "documentType", "senderPeppolId", "receiverPeppolId", "xml" ], "additionalProperties": false }, { "type": "object", "properties": { "inputType": { "const": "json", "type": "string" }, "environment": { "type": "string", "enum": [ "test", "production" ], "default": "test" }, "documentType": { "type": "string", "enum": [ "invoice", "creditNote" ] }, "senderPeppolId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[0-9]{4}:.+$" }, "receiverPeppolId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[0-9]{4}:.+$" }, "payload": { "type": "object", "additionalProperties": {} }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 120 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 120 }, "forceResubmit": { "type": "boolean" } }, "required": [ "inputType", "documentType", "senderPeppolId", "receiverPeppolId", "payload" ], "additionalProperties": false }, { "type": "object", "properties": { "inputType": { "const": "mapped", "type": "string" }, "environment": { "type": "string", "enum": [ "test", "production" ], "default": "test" }, "documentType": { "type": "string", "enum": [ "invoice", "creditNote" ] }, "senderPeppolId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[0-9]{4}:.+$" }, "receiverPeppolId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[0-9]{4}:.+$" }, "payload": { "type": "object", "additionalProperties": {} }, "mappingId": { "type": "string", "minLength": 1, "maxLength": 120 }, "sourceSystem": { "type": "string", "minLength": 1, "maxLength": 60 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 120 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 120 }, "forceResubmit": { "type": "boolean" } }, "required": [ "inputType", "documentType", "senderPeppolId", "receiverPeppolId", "payload" ], "additionalProperties": false } ] }, "example": { "inputType": "json", "environment": "production", "documentType": "invoice", "senderPeppolId": "0235:1004****59", "receiverPeppolId": "0235:1002****03", "payload": { "invoiceNumber": "INV-2026-000123", "issueDate": "2026-10-20", "dueDate": "2026-11-19", "currency": "AED", "buyer": { "name": "Sample Buyer FZ-LLC", "peppolId": "0235:1002****03" }, "lines": [ { "description": "Consulting services", "quantity": 1, "unitPrice": 1000, "vatCategory": "S", "vatRate": 5 } ] } } } } }, "responses": { "200": { "description": "The document is valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "documentTypeId": { "type": "string" }, "processId": { "type": "string" }, "warnings": { "type": "array", "items": {} }, "phormSkipped": { "type": "boolean" }, "normalized": { "type": "object", "properties": { "sender": { "type": "string" }, "receiver": { "type": "string" }, "invoiceNumber": { "type": "string" }, "issueDate": { "type": "string" }, "currency": { "type": "string" }, "payableAmount": { "type": "integer" }, "invoiceTypeCode": { "type": "string" }, "dueDate": { "type": "string" }, "supplierName": { "type": "string" }, "customerName": { "type": "string" }, "netAmount": { "type": "integer" }, "taxAmount": { "type": "integer" } } } } }, "example": { "valid": true, "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "warnings": [], "phormSkipped": false, "normalized": { "sender": "0235:1004****59", "receiver": "0235:1002****03", "invoiceNumber": "INV-2026-000123", "issueDate": "2026-10-20", "currency": "AED", "payableAmount": 1050, "invoiceTypeCode": "380", "dueDate": "2026-11-19", "supplierName": "Sample Trading LLC", "customerName": "Sample Buyer FZ-LLC", "netAmount": 1000, "taxAmount": 50 } } } } }, "400": { "description": "The document failed validation (or the request body is invalid — standard error shape).", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "documentTypeId": { "type": "string" }, "processId": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "xpath": { "type": "string" } } } } } }, "warnings": { "type": "array", "items": {} } } }, "example": { "valid": false, "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "error": { "code": "PINT_VALIDATION_FAILED", "message": "Document failed Peppol/PINT validation.", "details": [ { "code": "ibr-144-ae", "message": "Buyer address must contain street, city and country subdivision.", "xpath": "/Invoice/cac:AccountingCustomerParty" } ] }, "warnings": [] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/invoices/send": { "post": { "operationId": "postTenantInvoicesSend", "summary": "Send an invoice over Peppol", "description": "Validates and submits the document through the same pipeline as `POST /api/integrations/peppol/invoices` (storage, AP Core hand-off, outbox events, audit), authenticated with the user's session. The `Idempotency-Key` header is authoritative; a different `body.idempotencyKey` answers 400 `IDEMPOTENCY_KEY_CONFLICT`. A repeated key returns the original transaction with `idempotent: true`, except a failed transaction that never reached the access point, which is retried (or re-created with `forceResubmit: true`). A `tenant_user` may only send from an allowed participant (403 `SENDER_NOT_IN_USER_SCOPE`). The `documents` links in the response use the Integration API URLs (`/api/integrations/peppol/…`).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Invoice sending" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional de-duplication key (1–120 characters), scoped to the tenant. A repeat with the same key returns the original transaction (`idempotent: true`) instead of sending again.", "schema": { "type": "string", "maxLength": 120, "example": "INV-2026-000123" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "inputType": { "const": "xml", "type": "string" }, "environment": { "type": "string", "enum": [ "test", "production" ], "default": "test" }, "documentType": { "type": "string", "enum": [ "invoice", "creditNote" ] }, "senderPeppolId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[0-9]{4}:.+$" }, "receiverPeppolId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[0-9]{4}:.+$" }, "xml": { "type": "string", "minLength": 20, "maxLength": 15728640 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 120 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 120 }, "forceResubmit": { "type": "boolean" } }, "required": [ "inputType", "documentType", "senderPeppolId", "receiverPeppolId", "xml" ], "additionalProperties": false }, { "type": "object", "properties": { "inputType": { "const": "json", "type": "string" }, "environment": { "type": "string", "enum": [ "test", "production" ], "default": "test" }, "documentType": { "type": "string", "enum": [ "invoice", "creditNote" ] }, "senderPeppolId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[0-9]{4}:.+$" }, "receiverPeppolId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[0-9]{4}:.+$" }, "payload": { "type": "object", "additionalProperties": {} }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 120 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 120 }, "forceResubmit": { "type": "boolean" } }, "required": [ "inputType", "documentType", "senderPeppolId", "receiverPeppolId", "payload" ], "additionalProperties": false }, { "type": "object", "properties": { "inputType": { "const": "mapped", "type": "string" }, "environment": { "type": "string", "enum": [ "test", "production" ], "default": "test" }, "documentType": { "type": "string", "enum": [ "invoice", "creditNote" ] }, "senderPeppolId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[0-9]{4}:.+$" }, "receiverPeppolId": { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[0-9]{4}:.+$" }, "payload": { "type": "object", "additionalProperties": {} }, "mappingId": { "type": "string", "minLength": 1, "maxLength": 120 }, "sourceSystem": { "type": "string", "minLength": 1, "maxLength": 60 }, "correlationId": { "type": "string", "minLength": 1, "maxLength": 120 }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 120 }, "forceResubmit": { "type": "boolean" } }, "required": [ "inputType", "documentType", "senderPeppolId", "receiverPeppolId", "payload" ], "additionalProperties": false } ] }, "example": { "inputType": "json", "environment": "production", "documentType": "invoice", "senderPeppolId": "0235:1004****59", "receiverPeppolId": "0235:1002****03", "payload": { "invoiceNumber": "INV-2026-000123", "issueDate": "2026-10-20", "dueDate": "2026-11-19", "currency": "AED", "buyer": { "name": "Sample Buyer FZ-LLC", "peppolId": "0235:1002****03" }, "lines": [ { "description": "Consulting services", "quantity": 1, "unitPrice": 1000, "vatCategory": "S", "vatRate": 5 } ] } } } } }, "responses": { "202": { "description": "Accepted for Peppol delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionId": { "type": "string" }, "status": { "type": "string" }, "valid": { "type": "boolean" }, "documentTypeId": { "type": "string" }, "processId": { "type": "string" }, "correlationId": { "type": "string" }, "as4MessageId": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "idempotent": { "type": "boolean" }, "warnings": { "type": "array", "items": {} }, "validatorPhormSkipped": { "type": "boolean" }, "documents": { "type": "object", "properties": { "invoiceXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "string" } } }, "invoicePdf": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "null" }, "fileName": { "type": "null" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "null" }, "reason": { "type": "string" } } }, "sbdXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "null" }, "fileName": { "type": "null" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "null" }, "reason": { "type": "string" } } }, "tddXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "null" }, "fileName": { "type": "null" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "null" }, "reason": { "type": "string" } } }, "mlsXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "null" }, "fileName": { "type": "null" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "null" }, "reason": { "type": "string" } } }, "payloadXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "privileged": { "type": "boolean" }, "requiredScope": { "type": "string" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "string" } } } } }, "message": { "type": "string" } } }, "example": { "transactionId": "txn_1789562400000_9f3a…", "status": "queued", "valid": true, "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "correlationId": "cor_1789562400000_4d5e…", "as4MessageId": "f0debc61-…@peppol.azdanapps.com", "sbdhInstanceId": "6c1d2e3f-…", "idempotent": false, "warnings": [], "validatorPhormSkipped": false, "documents": { "invoiceXml": { "available": true, "fileId": "file_01J9Z3…", "fileName": "txn_1789562400000_9f3a….xml", "contentType": "application/xml", "downloadUrl": "/api/integrations/peppol/transactions/txn_1789562400000_9f3a…/files/invoice-xml" }, "invoicePdf": { "available": false, "fileId": null, "fileName": null, "contentType": "application/pdf", "downloadUrl": null, "reason": "not_generated" }, "sbdXml": { "available": false, "fileId": null, "fileName": null, "contentType": "application/xml", "downloadUrl": null, "reason": "not_stored" }, "tddXml": { "available": false, "fileId": null, "fileName": null, "contentType": "application/xml", "downloadUrl": null, "reason": "not_generated" }, "mlsXml": { "available": false, "fileId": null, "fileName": null, "contentType": "application/xml", "downloadUrl": null, "reason": "not_received" }, "payloadXml": { "available": true, "privileged": true, "requiredScope": "peppol:payload:read", "contentType": "application/xml", "downloadUrl": "/api/integrations/peppol/transactions/txn_1789562400000_9f3a…/xml" } }, "message": "Invoice accepted for Peppol delivery." } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "422": { "$ref": "#/components/responses/ErrUnprocessable" }, "500": { "$ref": "#/components/responses/ErrInternal" }, "502": { "$ref": "#/components/responses/ErrBadGateway" }, "503": { "$ref": "#/components/responses/ErrUnavailable" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/notification-settings": { "get": { "operationId": "getTenantNotificationSettings", "summary": "Get the tenant's email notification settings", "description": "Returns the tenant's notification settings (defaults when never saved, flagged `isDefault`), the resolved recipients (tenant admins, extra addresses and the effective list), and the platform's mail status: whether email is enabled and configured, which kinds are sent, and whether outside production all mail is redirected to a test mailbox. Readable by any tenant user.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "responses": { "200": { "description": "Settings view.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "types": { "type": "object", "properties": { "deliveryFailed": { "type": "boolean" }, "mlsRejected": { "type": "boolean" }, "inboundReceived": { "type": "boolean" }, "ftaLinkage": { "type": "boolean" } } }, "notifyAdmins": { "type": "boolean" }, "extraRecipients": { "type": "array", "items": { "type": "string" } }, "updatedAt": { "type": "string" }, "isDefault": { "type": "boolean" } } }, "recipients": { "type": "object", "properties": { "admins": { "type": "array", "items": { "type": "string" } }, "extra": { "type": "array", "items": { "type": "string" } }, "effective": { "type": "array", "items": { "type": "string" } } } }, "tenantName": { "type": "string" }, "platform": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "configured": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "string" } }, "redirected": { "type": "boolean" } } }, "limits": { "type": "object", "properties": { "maxExtraRecipients": { "type": "integer" } } } } }, "example": { "settings": { "enabled": true, "types": { "deliveryFailed": true, "mlsRejected": true, "inboundReceived": false, "ftaLinkage": true }, "notifyAdmins": true, "extraRecipients": [ "f***@example.com" ], "updatedAt": "2026-10-21T09:14:03.000Z", "isDefault": false }, "recipients": { "admins": [ "o***@example.com" ], "extra": [ "f***@example.com" ], "effective": [ "o***@example.com", "f***@example.com" ] }, "tenantName": "AZDAN Demo", "platform": { "enabled": true, "configured": true, "kinds": [ "delivery_failed", "mls_rejected", "inbound_received", "fta_onboarded", "fta_reverified", "fta_offboarded", "fta_offboard_pending", "tenant_suspended", "tenant_reactivated", "tenant_welcome" ], "redirected": false }, "limits": { "maxExtraRecipients": 10 } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "put": { "operationId": "putTenantNotificationSettings", "summary": "Save the tenant's email notification settings", "description": "Replaces the tenant's notification settings: master switch, per-type switches, whether tenant admins receive mail, and extra recipients (trimmed, lower-cased, de-duplicated, at most 10 after normalisation). `tenant_admin` only; denials are audited. Returns the same view as the GET. The audit row records which fields changed and a recipient count, never addresses.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "types": { "type": "object", "properties": { "deliveryFailed": { "type": "boolean" }, "mlsRejected": { "type": "boolean" }, "inboundReceived": { "type": "boolean" }, "ftaLinkage": { "type": "boolean" } }, "required": [ "deliveryFailed", "mlsRejected", "inboundReceived", "ftaLinkage" ], "additionalProperties": false }, "notifyAdmins": { "type": "boolean" }, "extraRecipients": { "type": "array", "items": { "type": "string", "maxLength": 254 }, "maxItems": 50, "default": [] } }, "required": [ "enabled", "types", "notifyAdmins" ], "additionalProperties": false }, "example": { "enabled": true, "types": { "deliveryFailed": true, "mlsRejected": true, "inboundReceived": false, "ftaLinkage": true }, "notifyAdmins": true, "extraRecipients": [ "f***@example.com" ] } } } }, "responses": { "200": { "description": "The updated settings view (same shape as the GET).", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "types": { "type": "object", "properties": { "deliveryFailed": { "type": "boolean" }, "mlsRejected": { "type": "boolean" }, "inboundReceived": { "type": "boolean" }, "ftaLinkage": { "type": "boolean" } } }, "notifyAdmins": { "type": "boolean" }, "extraRecipients": { "type": "array", "items": { "type": "string" } }, "updatedAt": { "type": "string" }, "isDefault": { "type": "boolean" } } }, "recipients": { "type": "object", "properties": { "admins": { "type": "array", "items": { "type": "string" } }, "extra": { "type": "array", "items": { "type": "string" } }, "effective": { "type": "array", "items": { "type": "string" } } } }, "tenantName": { "type": "string" }, "platform": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "configured": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "string" } }, "redirected": { "type": "boolean" } } }, "limits": { "type": "object", "properties": { "maxExtraRecipients": { "type": "integer" } } } } }, "example": { "settings": { "enabled": true, "types": { "deliveryFailed": true, "mlsRejected": true, "inboundReceived": false, "ftaLinkage": true }, "notifyAdmins": true, "extraRecipients": [ "f***@example.com" ], "updatedAt": "2026-10-21T09:14:03.000Z", "isDefault": false }, "recipients": { "admins": [ "o***@example.com" ], "extra": [ "f***@example.com" ], "effective": [ "o***@example.com", "f***@example.com" ] }, "tenantName": "AZDAN Demo", "platform": { "enabled": true, "configured": true, "kinds": [ "delivery_failed", "mls_rejected" ], "redirected": false }, "limits": { "maxExtraRecipients": 10 } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/notification-settings/test": { "post": { "operationId": "postTenantNotificationSettingsTest", "summary": "Send a test notification email", "description": "Sends a bilingual test email to the recipients the settings name (admins when `notifyAdmins`, plus extra addresses), regardless of the master switch. At most once a minute per tenant. Each send is logged in the mail notification log. `tenant_admin` only. Per-recipient results include the mail server's error text on failure.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "Send results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "recipient": { "type": "string" }, "status": { "type": "string" } } } }, "redirected": { "type": "boolean" } } }, "example": { "sent": 1, "failed": 1, "results": [ { "recipient": "o***@example.com", "status": "sent" }, { "recipient": "f***@example.com", "status": "failed", "error": "550 Mailbox unavailable" } ], "redirected": false } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "429": { "$ref": "#/components/responses/ErrTooManyRequests" }, "500": { "$ref": "#/components/responses/ErrInternal" }, "503": { "$ref": "#/components/responses/ErrUnavailable" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/notification-settings/history": { "get": { "operationId": "getTenantNotificationSettingsHistory", "summary": "List the tenant's recent notification emails", "description": "The tenant's own notification emails, newest first (`limit` 1–100, default 25), excluding ones skipped by settings. Shows whether each failed but not the mail server's error text.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Recent emails.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "recipient": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "transactionId": { "type": "string" }, "createdAt": { "type": "string" }, "sentAt": { "type": "string" }, "failed": { "type": "boolean" } } } } } }, "example": { "items": [ { "id": "6716f2b0…3c11", "kind": "delivery_failed", "recipient": "o***@example.com", "status": "sent", "attempts": 1, "transactionId": "txn_8F2K…", "createdAt": "2026-10-21T09:14:03.000Z", "sentAt": "2026-10-21T09:14:41.000Z", "failed": false } ] } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/company-profiles": { "get": { "operationId": "getTenantCompanyProfiles", "summary": "List company invoicing profiles", "description": "Lists the tenant's subsidiaries (default first) with their seller invoicing profile and a server-derived `missingFields` checklist naming the PINT-AE rule behind each gap (e.g. `ibr-150-ae`). `uaeScheme` is true when the subsidiary has an active outbound participant with EAS `0235`, which makes trade-licence fields mandatory. tenant_user sees only subsidiaries on their allow-list. Not paginated.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Master data" ], "responses": { "200": { "description": "Company profiles.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "subsidiaryId": { "type": "string" }, "name": { "type": "string" }, "legalName": { "type": "string" }, "country": { "type": "string" }, "taxRegistrationNumber": { "type": "string" }, "defaultCurrency": { "type": "string" }, "isDefault": { "type": "boolean" }, "status": { "type": "string" }, "invoiceProfile": { "type": "object", "properties": { "legalRegistrationId": { "type": "string" }, "legalRegistrationType": { "type": "string" }, "legalRegistrationAuthorityName": { "type": "string" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "additionalStreetLine": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" } } }, "defaultPaymentMeansCode": { "type": "string" }, "defaultPaymentAccountId": { "type": "string" }, "defaultPaymentTermsNote": { "type": "string" }, "updatedAt": { "type": "string" } } }, "uaeScheme": { "type": "boolean" }, "missingFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "rule": { "type": "string" }, "why": { "type": "string" } } } } } } } } }, "example": { "items": [ { "subsidiaryId": "sub_2Lm…", "name": "AZDAN Demo", "legalName": "AZDAN Demo Trading L.L.C.", "country": "AE", "taxRegistrationNumber": "1007****03", "defaultCurrency": "AED", "isDefault": true, "status": "active", "invoiceProfile": { "legalRegistrationId": "CN-98****", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "", "address": { "street": "Al Wasl Road", "additionalStreetLine": "", "city": "Dubai", "region": "DXB", "postalCode": "00000", "country": "AE" }, "defaultPaymentMeansCode": "30", "defaultPaymentAccountId": "AE07****0001", "defaultPaymentTermsNote": "Net 30", "updatedAt": "2026-10-21T09:14:03.000Z" }, "uaeScheme": true, "missingFields": [ { "field": "invoiceProfile.legalRegistrationAuthorityName", "label": "Issuing authority", "rule": "ibr-172-ae", "why": "Mandatory for a trade licence; for a passport it must be the ISO 3166-1 issuing country." } ] } ] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/company-profiles/{subsidiaryId}": { "put": { "operationId": "putTenantCompanyProfilesBySubsidiaryId", "summary": "Update a company invoicing profile", "description": "Updates the seller invoicing profile of one of the tenant's subsidiaries; only the fields sent are changed (partial update despite PUT). `address`, when sent, replaces the whole address and its `country` sets the subsidiary's country. `legalName`, `taxRegistrationNumber` and `defaultCurrency` are written to the subsidiary itself. `tenant_admin` only; audited. Returns the recomputed profile with `missingFields`.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Master data" ], "parameters": [ { "name": "subsidiaryId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "legalName": { "type": "string", "maxLength": 200 }, "taxRegistrationNumber": { "type": "string", "maxLength": 80 }, "defaultCurrency": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z]{3}$" }, { "const": "", "type": "string" } ] }, "legalRegistrationId": { "type": "string", "maxLength": 80 }, "legalRegistrationType": { "type": "string", "enum": [ "", "TL", "EID", "PAS", "CD" ] }, "legalRegistrationAuthorityName": { "type": "string", "maxLength": 200 }, "address": { "type": "object", "properties": { "street": { "type": "string", "maxLength": 200 }, "additionalStreetLine": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "maxLength": 120 }, "region": { "type": "string", "maxLength": 120 }, "postalCode": { "type": "string", "maxLength": 40 }, "country": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z]{2}$" }, { "const": "", "type": "string" } ] } }, "additionalProperties": false }, "defaultPaymentMeansCode": { "anyOf": [ { "type": "string", "pattern": "^[0-9]{1,3}$" }, { "const": "", "type": "string" } ] }, "defaultPaymentAccountId": { "type": "string", "maxLength": 80 }, "defaultPaymentTermsNote": { "type": "string", "maxLength": 500 } }, "additionalProperties": false }, "example": { "legalRegistrationId": "CN-98****", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Dubai Economy and Tourism", "address": { "street": "Al Wasl Road", "city": "Dubai", "region": "DXB", "postalCode": "00000", "country": "AE" }, "defaultPaymentMeansCode": "30", "defaultPaymentAccountId": "AE07****0001" } } } }, "responses": { "200": { "description": "The updated profile.", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyProfile": { "type": "object", "properties": { "subsidiaryId": { "type": "string" }, "name": { "type": "string" }, "legalName": { "type": "string" }, "country": { "type": "string" }, "taxRegistrationNumber": { "type": "string" }, "defaultCurrency": { "type": "string" }, "isDefault": { "type": "boolean" }, "status": { "type": "string" }, "invoiceProfile": { "type": "object", "properties": { "legalRegistrationId": { "type": "string" }, "legalRegistrationType": { "type": "string" }, "legalRegistrationAuthorityName": { "type": "string" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "additionalStreetLine": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" } } }, "defaultPaymentMeansCode": { "type": "string" }, "defaultPaymentAccountId": { "type": "string" }, "defaultPaymentTermsNote": { "type": "string" }, "updatedAt": { "type": "string" } } }, "uaeScheme": { "type": "boolean" }, "missingFields": { "type": "array", "items": {} } } } } }, "example": { "companyProfile": { "subsidiaryId": "sub_2Lm…", "name": "AZDAN Demo", "legalName": "AZDAN Demo Trading L.L.C.", "country": "AE", "taxRegistrationNumber": "1007****03", "defaultCurrency": "AED", "isDefault": true, "status": "active", "invoiceProfile": { "legalRegistrationId": "CN-98****", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Dubai Economy and Tourism", "address": { "street": "Al Wasl Road", "additionalStreetLine": "", "city": "Dubai", "region": "DXB", "postalCode": "00000", "country": "AE" }, "defaultPaymentMeansCode": "30", "defaultPaymentAccountId": "AE07****0001", "defaultPaymentTermsNote": "Net 30", "updatedAt": "2026-10-21T09:14:03.000Z" }, "uaeScheme": true, "missingFields": [] } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/customers": { "get": { "operationId": "getTenantCustomers", "summary": "List customers", "description": "Lists the tenant's customers sorted by display name. Defaults to `status=active` (`all` includes disabled); archived (deleted) customers never appear. `q` searches display name, legal name, Peppol ID and TRN (case-insensitive); `subsidiaryId` narrows to one company. tenant_user sees tenant-wide customers plus those of subsidiaries on their allow-list. Page-number pagination (default 50, max 200).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Master data" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "disabled", "all" ] } }, { "name": "subsidiaryId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "A page of customers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "customerId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "displayName": { "type": "string" }, "legalName": { "type": "string" }, "peppolId": { "type": "string" }, "schemeId": { "type": "string" }, "endpointValue": { "type": "string" }, "taxRegistrationNumber": { "type": "string" }, "legalRegistrationId": { "type": "string" }, "legalRegistrationType": { "type": "string" }, "legalRegistrationAuthorityName": { "type": "string" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "additionalStreetLine": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" } } }, "contact": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "notes": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } }, "page": { "type": "object", "properties": { "number": { "type": "integer" }, "size": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } }, "example": { "items": [ { "customerId": "cust_a81f…", "subsidiaryId": "", "displayName": "Gulf Trading", "legalName": "Gulf Trading L.L.C.", "peppolId": "0235:1004****59", "schemeId": "0235", "endpointValue": "1004****59", "taxRegistrationNumber": "1004****59", "legalRegistrationId": "CN-12****", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Dubai Economy and Tourism", "address": { "street": "Sheikh Zayed Road", "additionalStreetLine": "", "city": "Dubai", "region": "DXB", "postalCode": "00000", "country": "AE" }, "contact": { "email": "o***@example.com", "phone": "+9714*****00" }, "notes": "", "status": "active", "createdAt": "2026-08-04T07:30:00.000Z", "updatedAt": "2026-10-21T09:14:03.000Z" } ], "page": { "number": 1, "size": 50, "total": 1, "totalPages": 1 } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "post": { "operationId": "postTenantCustomers", "summary": "Create a customer", "description": "Creates a customer. `peppolId` must be `NNNN:value` with an EAS scheme on the OpenPeppol active list and is split into `schemeId` / `endpointValue`; country codes are upper-cased. A Peppol ID already used by another customer of the tenant returns 409. `tenant_admin` only; audited.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Master data" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "legalName": { "type": "string", "maxLength": 200 }, "subsidiaryId": { "type": "string", "maxLength": 80 }, "peppolId": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[0-9]{4}:.+$" }, { "const": "", "type": "string" } ] }, "taxRegistrationNumber": { "type": "string", "maxLength": 80 }, "legalRegistrationId": { "type": "string", "maxLength": 80 }, "legalRegistrationType": { "type": "string", "enum": [ "", "TL", "CL", "EID", "PAS", "CD" ] }, "legalRegistrationAuthorityName": { "type": "string", "maxLength": 200 }, "address": { "type": "object", "properties": { "street": { "type": "string", "maxLength": 200 }, "additionalStreetLine": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "maxLength": 120 }, "region": { "type": "string", "maxLength": 120 }, "postalCode": { "type": "string", "maxLength": 40 }, "country": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z]{2}$" }, { "const": "", "type": "string" } ] } }, "additionalProperties": false }, "contact": { "type": "object", "properties": { "email": { "anyOf": [ { "type": "string", "format": "email", "maxLength": 200 }, { "const": "", "type": "string" } ] }, "phone": { "type": "string", "maxLength": 60 } }, "additionalProperties": false }, "notes": { "type": "string", "maxLength": 1000 }, "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "required": [ "displayName" ], "additionalProperties": false }, "example": { "displayName": "Gulf Trading", "legalName": "Gulf Trading L.L.C.", "peppolId": "0235:1004****59", "taxRegistrationNumber": "1004****59", "legalRegistrationId": "CN-12****", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Dubai Economy and Tourism", "address": { "street": "Sheikh Zayed Road", "city": "Dubai", "region": "DXB", "postalCode": "00000", "country": "AE" }, "contact": { "email": "o***@example.com", "phone": "+9714*****00" } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "customerId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "displayName": { "type": "string" }, "legalName": { "type": "string" }, "peppolId": { "type": "string" }, "schemeId": { "type": "string" }, "endpointValue": { "type": "string" }, "taxRegistrationNumber": { "type": "string" }, "legalRegistrationId": { "type": "string" }, "legalRegistrationType": { "type": "string" }, "legalRegistrationAuthorityName": { "type": "string" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "additionalStreetLine": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" } } }, "contact": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "notes": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } }, "example": { "customer": { "customerId": "cust_a81f…", "subsidiaryId": "", "displayName": "Gulf Trading", "legalName": "Gulf Trading L.L.C.", "peppolId": "0235:1004****59", "schemeId": "0235", "endpointValue": "1004****59", "taxRegistrationNumber": "1004****59", "legalRegistrationId": "CN-12****", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Dubai Economy and Tourism", "address": { "street": "Sheikh Zayed Road", "additionalStreetLine": "", "city": "Dubai", "region": "DXB", "postalCode": "00000", "country": "AE" }, "contact": { "email": "o***@example.com", "phone": "+9714*****00" }, "notes": "", "status": "active", "createdAt": "2026-08-04T07:30:00.000Z", "updatedAt": "2026-10-21T09:14:03.000Z" } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "409": { "$ref": "#/components/responses/ErrConflict" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/customers/{customerId}": { "get": { "operationId": "getTenantCustomersByCustomerId", "summary": "Get a customer", "description": "Returns one non-archived customer. A subsidiary-scoped customer outside a tenant_user's allow-list returns 404, the same as a missing one.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Master data" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "customerId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "displayName": { "type": "string" }, "legalName": { "type": "string" }, "peppolId": { "type": "string" }, "schemeId": { "type": "string" }, "endpointValue": { "type": "string" }, "taxRegistrationNumber": { "type": "string" }, "legalRegistrationId": { "type": "string" }, "legalRegistrationType": { "type": "string" }, "legalRegistrationAuthorityName": { "type": "string" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "additionalStreetLine": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" } } }, "contact": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "notes": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } }, "example": { "customer": { "customerId": "cust_a81f…", "subsidiaryId": "", "displayName": "Gulf Trading", "legalName": "Gulf Trading L.L.C.", "peppolId": "0235:1004****59", "schemeId": "0235", "endpointValue": "1004****59", "taxRegistrationNumber": "1004****59", "legalRegistrationId": "CN-12****", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Dubai Economy and Tourism", "address": { "street": "Sheikh Zayed Road", "additionalStreetLine": "", "city": "Dubai", "region": "DXB", "postalCode": "00000", "country": "AE" }, "contact": { "email": "o***@example.com", "phone": "+9714*****00" }, "notes": "", "status": "active", "createdAt": "2026-08-04T07:30:00.000Z", "updatedAt": "2026-10-21T09:14:03.000Z" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "delete": { "operationId": "deleteTenantCustomersByCustomerId", "summary": "Archive a customer", "description": "Soft delete: sets `deletedAt` and `status: disabled`. The customer disappears from lists and detail reads; the record is kept. `tenant_admin` only; audited.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Master data" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "Archived.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "customerId": { "type": "string" } } }, "example": { "ok": true, "customerId": "cust_a81f…" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "patch": { "operationId": "patchTenantCustomersByCustomerId", "summary": "Update a customer", "description": "Updates only the fields sent. Sending `address` or `contact` replaces that whole sub-object; sending `peppolId` re-derives `schemeId` / `endpointValue`. `tenant_admin` only; audited with the list of changed fields.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Master data" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "legalName": { "type": "string", "maxLength": 200 }, "subsidiaryId": { "type": "string", "maxLength": 80 }, "peppolId": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 200, "pattern": "^[0-9]{4}:.+$" }, { "const": "", "type": "string" } ] }, "taxRegistrationNumber": { "type": "string", "maxLength": 80 }, "legalRegistrationId": { "type": "string", "maxLength": 80 }, "legalRegistrationType": { "type": "string", "enum": [ "", "TL", "CL", "EID", "PAS", "CD" ] }, "legalRegistrationAuthorityName": { "type": "string", "maxLength": 200 }, "address": { "type": "object", "properties": { "street": { "type": "string", "maxLength": 200 }, "additionalStreetLine": { "type": "string", "maxLength": 200 }, "city": { "type": "string", "maxLength": 120 }, "region": { "type": "string", "maxLength": 120 }, "postalCode": { "type": "string", "maxLength": 40 }, "country": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z]{2}$" }, { "const": "", "type": "string" } ] } }, "additionalProperties": false }, "contact": { "type": "object", "properties": { "email": { "anyOf": [ { "type": "string", "format": "email", "maxLength": 200 }, { "const": "", "type": "string" } ] }, "phone": { "type": "string", "maxLength": 60 } }, "additionalProperties": false }, "notes": { "type": "string", "maxLength": 1000 }, "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "additionalProperties": false }, "example": { "contact": { "email": "o***@example.com", "phone": "+9714*****00" }, "status": "active" } } } }, "responses": { "200": { "description": "The updated customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "customerId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "displayName": { "type": "string" }, "legalName": { "type": "string" }, "peppolId": { "type": "string" }, "schemeId": { "type": "string" }, "endpointValue": { "type": "string" }, "taxRegistrationNumber": { "type": "string" }, "legalRegistrationId": { "type": "string" }, "legalRegistrationType": { "type": "string" }, "legalRegistrationAuthorityName": { "type": "string" }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "additionalStreetLine": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string" } } }, "contact": { "type": "object", "properties": { "email": { "type": "string" }, "phone": { "type": "string" } } }, "notes": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } }, "example": { "customer": { "customerId": "cust_a81f…", "subsidiaryId": "", "displayName": "Gulf Trading", "legalName": "Gulf Trading L.L.C.", "peppolId": "0235:1004****59", "schemeId": "0235", "endpointValue": "1004****59", "taxRegistrationNumber": "1004****59", "legalRegistrationId": "CN-12****", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Dubai Economy and Tourism", "address": { "street": "Sheikh Zayed Road", "additionalStreetLine": "", "city": "Dubai", "region": "DXB", "postalCode": "00000", "country": "AE" }, "contact": { "email": "o***@example.com", "phone": "+9714*****00" }, "notes": "", "status": "active", "createdAt": "2026-08-04T07:30:00.000Z", "updatedAt": "2026-10-21T09:14:03.000Z" } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "409": { "$ref": "#/components/responses/ErrConflict" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/items": { "get": { "operationId": "getTenantItems", "summary": "List items", "description": "Lists the tenant's items sorted by name. Defaults to `status=active` (`all` includes disabled); archived items never appear. `q` searches name, description and code; `subsidiaryId` narrows to one company. tenant_user sees tenant-wide items plus those of subsidiaries on their allow-list. Page-number pagination (default 50, max 200).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Master data" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "disabled", "all" ] } }, { "name": "subsidiaryId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } } ], "responses": { "200": { "description": "A page of items.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "unitCode": { "type": "string" }, "unitLabel": { "type": "string" }, "defaultUnitPrice": { "type": "string" }, "currency": { "type": "string" }, "vatCategory": { "type": "string" }, "vatPercent": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } }, "page": { "type": "object", "properties": { "number": { "type": "integer" }, "size": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } }, "example": { "items": [ { "itemId": "item_3c9d…", "subsidiaryId": "", "code": "SRV-001", "name": "Consulting services", "description": "Hourly consulting", "unitCode": "HUR", "unitLabel": "Hour", "defaultUnitPrice": "450.00", "currency": "AED", "vatCategory": "S", "vatPercent": "5", "status": "active", "createdAt": "2026-08-04T07:35:00.000Z", "updatedAt": "2026-10-21T09:14:03.000Z" } ], "page": { "number": 1, "size": 50, "total": 1, "totalPages": 1 } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "post": { "operationId": "postTenantItems", "summary": "Create an item", "description": "Creates a catalogue item. Prices and VAT percentages are decimal strings, kept as strings end to end; `currency` is upper-cased. An item code already used in the tenant returns 409. `unitCode` reads back as `EA` when empty. `tenant_admin` only; audited.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Master data" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "code": { "type": "string", "maxLength": 80 }, "subsidiaryId": { "type": "string", "maxLength": 80 }, "unitCode": { "type": "string", "maxLength": 12 }, "unitLabel": { "type": "string", "maxLength": 60 }, "defaultUnitPrice": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "const": "", "type": "string" } ] }, "currency": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z]{3}$" }, { "const": "", "type": "string" } ] }, "vatCategory": { "type": "string", "maxLength": 4 }, "vatPercent": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,4})?$" }, { "const": "", "type": "string" } ] }, "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "Consulting services", "description": "Hourly consulting", "code": "SRV-001", "unitCode": "HUR", "unitLabel": "Hour", "defaultUnitPrice": "450.00", "currency": "AED", "vatCategory": "S", "vatPercent": "5" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "itemId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "unitCode": { "type": "string" }, "unitLabel": { "type": "string" }, "defaultUnitPrice": { "type": "string" }, "currency": { "type": "string" }, "vatCategory": { "type": "string" }, "vatPercent": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } }, "example": { "item": { "itemId": "item_3c9d…", "subsidiaryId": "", "code": "SRV-001", "name": "Consulting services", "description": "Hourly consulting", "unitCode": "HUR", "unitLabel": "Hour", "defaultUnitPrice": "450.00", "currency": "AED", "vatCategory": "S", "vatPercent": "5", "status": "active", "createdAt": "2026-08-04T07:35:00.000Z", "updatedAt": "2026-10-21T09:14:03.000Z" } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "409": { "$ref": "#/components/responses/ErrConflict" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/items/{itemId}": { "get": { "operationId": "getTenantItemsByItemId", "summary": "Get an item", "description": "Returns one non-archived item. A subsidiary-scoped item outside a tenant_user's allow-list returns 404, the same as a missing one.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Master data" ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The item.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "itemId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "unitCode": { "type": "string" }, "unitLabel": { "type": "string" }, "defaultUnitPrice": { "type": "string" }, "currency": { "type": "string" }, "vatCategory": { "type": "string" }, "vatPercent": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } }, "example": { "item": { "itemId": "item_3c9d…", "subsidiaryId": "", "code": "SRV-001", "name": "Consulting services", "description": "Hourly consulting", "unitCode": "HUR", "unitLabel": "Hour", "defaultUnitPrice": "450.00", "currency": "AED", "vatCategory": "S", "vatPercent": "5", "status": "active", "createdAt": "2026-08-04T07:35:00.000Z", "updatedAt": "2026-10-21T09:14:03.000Z" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "delete": { "operationId": "deleteTenantItemsByItemId", "summary": "Archive an item", "description": "Soft delete: sets `deletedAt` and `status: disabled`. The item disappears from lists and detail reads; the record is kept. `tenant_admin` only; audited.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Master data" ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "Archived.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "itemId": { "type": "string" } } }, "example": { "ok": true, "itemId": "item_3c9d…" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "patch": { "operationId": "patchTenantItemsByItemId", "summary": "Update an item", "description": "Updates only the fields sent. `tenant_admin` only; audited with the list of changed fields.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Master data" ], "parameters": [ { "name": "itemId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "code": { "type": "string", "maxLength": 80 }, "subsidiaryId": { "type": "string", "maxLength": 80 }, "unitCode": { "type": "string", "maxLength": 12 }, "unitLabel": { "type": "string", "maxLength": 60 }, "defaultUnitPrice": { "anyOf": [ { "type": "string", "pattern": "^-?\\d{1,15}(\\.\\d{1,6})?$" }, { "const": "", "type": "string" } ] }, "currency": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z]{3}$" }, { "const": "", "type": "string" } ] }, "vatCategory": { "type": "string", "maxLength": 4 }, "vatPercent": { "anyOf": [ { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,4})?$" }, { "const": "", "type": "string" } ] }, "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "additionalProperties": false }, "example": { "defaultUnitPrice": "475.00", "vatPercent": "5" } } } }, "responses": { "200": { "description": "The updated item.", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "type": "object", "properties": { "itemId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "unitCode": { "type": "string" }, "unitLabel": { "type": "string" }, "defaultUnitPrice": { "type": "string" }, "currency": { "type": "string" }, "vatCategory": { "type": "string" }, "vatPercent": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } }, "example": { "item": { "itemId": "item_3c9d…", "subsidiaryId": "", "code": "SRV-001", "name": "Consulting services", "description": "Hourly consulting", "unitCode": "HUR", "unitLabel": "Hour", "defaultUnitPrice": "475.00", "currency": "AED", "vatCategory": "S", "vatPercent": "5", "status": "active", "createdAt": "2026-08-04T07:35:00.000Z", "updatedAt": "2026-10-21T09:14:03.000Z" } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "409": { "$ref": "#/components/responses/ErrConflict" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/transactions/{transactionId}/files": { "get": { "operationId": "getTenantTransactionsByTransactionIdFiles", "summary": "List the stored files of a transaction", "description": "The `transaction_files` rows whose `transactionId` equals the path id, oldest first, in the tenant-safe projection (no object-storage coordinates, KMS key id or spool path; `encryption.mode` and `legacyLocalPathPending` only). A transaction outside a `tenant_user`'s scope answers 404, like an unknown id.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Documents & files" ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The transaction's files.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string" }, "transactionId": { "type": "string" }, "tenantId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "direction": { "type": "string" }, "environment": { "type": "string" }, "transactionType": { "type": "string" }, "fileType": { "type": "string" }, "role": { "type": "string" }, "originalName": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "sha256": { "type": "string" }, "source": { "type": "string" }, "parentTransactionId": { "type": "string" }, "apTddTransactionId": { "type": "string" }, "apCoreMessageId": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "storageProvider": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "encryption": { "type": "object", "properties": { "mode": { "type": "string" } } }, "legacyLocalPathPending": { "type": "boolean" } } } } } }, "example": { "items": [ { "fileId": "file_01J9Z3…", "transactionId": "txn_1789562400000_9f3a…", "tenantId": "tnt_7Q2X…", "subsidiaryId": "sub_1789…_a1b2", "direction": "outbound", "environment": "production", "transactionType": "", "fileType": "payload", "role": "payload", "originalName": "txn_1789562400000_9f3a….xml", "filename": "txn_1789562400000_9f3a….xml", "contentType": "application/xml", "sizeBytes": 18432, "sha256": "3f7a9c…", "source": "", "parentTransactionId": "", "apTddTransactionId": "", "apCoreMessageId": "", "sbdhInstanceId": "", "storageProvider": "oci", "status": "uploaded", "createdAt": "2026-10-20T09:00:01.000Z", "updatedAt": "2026-10-20T09:00:01.000Z", "encryption": { "mode": "NONE" }, "legacyLocalPathPending": false }, { "fileId": "file_01J9Z5…", "transactionId": "txn_1789562400000_9f3a…", "tenantId": "tnt_7Q2X…", "subsidiaryId": "sub_1789…_a1b2", "direction": "outbound", "environment": "production", "transactionType": "taxdata", "fileType": "tdd_xml", "role": "tdd_xml", "originalName": "6c1d2e3f-….xml", "filename": "6c1d2e3f-….xml", "contentType": "application/xml", "sizeBytes": 4210, "sha256": "a91e04…", "source": "ap_core_generated_tdd", "parentTransactionId": "txn_1789562400000_9f3a…", "apTddTransactionId": "b7e2c1d0-…", "apCoreMessageId": "2a4b6c8d-…@peppol.azdanapps.com", "sbdhInstanceId": "9d8c7b6a-…", "storageProvider": "oci", "status": "uploaded", "createdAt": "2026-10-20T09:03:12.000Z", "updatedAt": "2026-10-20T09:03:12.000Z", "encryption": { "mode": "NONE" }, "legacyLocalPathPending": false } ] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/files/{fileId}/preview": { "get": { "operationId": "getTenantFilesByFileIdPreview", "summary": "Preview a stored file inline", "description": "Reads the first 512 KiB of the object from object storage and returns a structured preview, so a browser can show XML without following a signed URL. XML / SBDH files are parsed (SBDH header + UBL summary) and returned as `rawText`; JSON is pretty-printed; PDF and binary files return metadata only (`summary.reason: \"binary-not-inlined\"`). Only object-storage files can be previewed (400 otherwise). Each preview is audit-logged (`storage.file.preview`). Files outside a `tenant_user`'s scope answer 404.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Documents & files" ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The file metadata and preview.", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "properties": { "fileId": { "type": "string" }, "transactionId": { "type": "string" }, "tenantId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "direction": { "type": "string" }, "environment": { "type": "string" }, "transactionType": { "type": "string" }, "fileType": { "type": "string" }, "role": { "type": "string" }, "originalName": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "sha256": { "type": "string" }, "source": { "type": "string" }, "parentTransactionId": { "type": "string" }, "apTddTransactionId": { "type": "string" }, "apCoreMessageId": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "storageProvider": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "encryption": { "type": "object", "properties": { "mode": { "type": "string" } } }, "legacyLocalPathPending": { "type": "boolean" } } }, "preview": { "type": "object", "properties": { "kind": { "type": "string" }, "summary": { "type": "object", "properties": { "hasSbdh": { "type": "boolean" }, "documentRoot": { "type": "string" }, "senderId": { "type": "null" }, "receiverId": { "type": "null" }, "instanceIdentifier": { "type": "null" }, "documentId": { "type": "string" }, "issueDate": { "type": "string" }, "payableAmount": { "type": "object", "properties": { "currency": { "type": "string" }, "value": { "type": "string" } } } } }, "sbdhHeader": { "type": "null" }, "documentSummary": { "type": "object", "properties": { "rootElement": { "type": "string" }, "id": { "type": "string" }, "issueDate": { "type": "string" }, "documentCurrencyCode": { "type": "string" }, "payableAmount": { "type": "object", "properties": { "currency": { "type": "string" }, "value": { "type": "string" } } } } }, "rawText": { "type": "string" }, "truncated": { "type": "boolean" } } } } }, "example": { "file": { "fileId": "file_01J9Z3…", "transactionId": "txn_1789562400000_9f3a…", "tenantId": "tnt_7Q2X…", "subsidiaryId": "sub_1789…_a1b2", "direction": "outbound", "environment": "production", "transactionType": "", "fileType": "payload", "role": "payload", "originalName": "txn_1789562400000_9f3a….xml", "filename": "txn_1789562400000_9f3a….xml", "contentType": "application/xml", "sizeBytes": 18432, "sha256": "3f7a9c…", "source": "", "parentTransactionId": "", "apTddTransactionId": "", "apCoreMessageId": "", "sbdhInstanceId": "", "storageProvider": "oci", "status": "uploaded", "createdAt": "2026-10-20T09:00:01.000Z", "updatedAt": "2026-10-20T09:00:01.000Z", "encryption": { "mode": "NONE" }, "legacyLocalPathPending": false }, "preview": { "kind": "xml", "summary": { "hasSbdh": false, "documentRoot": "Invoice", "senderId": null, "receiverId": null, "instanceIdentifier": null, "documentId": "INV-2026-000123", "issueDate": "2026-10-20", "payableAmount": { "currency": "AED", "value": "1050.00" } }, "sbdhHeader": null, "documentSummary": { "rootElement": "Invoice", "id": "INV-2026-000123", "issueDate": "2026-10-20", "documentCurrencyCode": "AED", "payableAmount": { "currency": "AED", "value": "1050.00" } }, "rawText": "…", "truncated": false } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/files/{fileId}/download-url": { "post": { "operationId": "postTenantFilesByFileIdDownloadUrl", "summary": "Create a short-lived download URL for a file", "description": "Mints a pre-authenticated object-storage URL for one file. `ttlSeconds` is 30–300 (the storage profile default applies when omitted). Only object-storage files qualify (400 otherwise). Audit-logged (`storage.file.download_url`). Files outside a `tenant_user`'s scope answer 404.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Documents & files" ], "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ttlSeconds": { "type": "integer", "minimum": 30, "maximum": 300 } }, "additionalProperties": false, "default": {} }, "example": { "ttlSeconds": 120 } } } }, "responses": { "200": { "description": "The signed URL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "ttlSeconds": { "type": "integer" }, "fileId": { "type": "string" } } }, "example": { "url": "https://objectstorage.me-dubai-1.oraclecloud.com/p/AbCd…/n/…/b/…/o/…", "ttlSeconds": 120, "fileId": "file_01J9Z3…" } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" }, "502": { "$ref": "#/components/responses/ErrBadGateway" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/subsidiaries": { "get": { "operationId": "getTenantSubsidiaries", "summary": "List the tenant's companies", "description": "Every non-deleted subsidiary (company) of the tenant, default first, then by name, with `participantCount` and `locationCount`. A `tenant_user` only receives the companies on their `allowedSubsidiaryIds`.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Company & participants" ], "responses": { "200": { "description": "The companies.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "subsidiaryId": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "legalName": { "type": "string" }, "code": { "type": "string" }, "country": { "type": "string" }, "taxRegistrationNumber": { "type": "string" }, "netsuiteSubsidiaryId": { "type": "string" }, "defaultCurrency": { "type": "string" }, "status": { "type": "string" }, "isDefault": { "type": "boolean" }, "sellerProfile": { "type": "object", "properties": { "legalRegistrationId": { "type": "string" }, "legalRegistrationType": { "type": "string" }, "legalRegistrationAuthorityName": { "type": "string" }, "address": { "type": "object", "properties": { "streetName": { "type": "string" }, "cityName": { "type": "string" }, "countrySubentity": { "type": "string" }, "postalZone": { "type": "string" } } } } }, "deletedAt": { "type": "null" }, "createdBy": { "type": "null" }, "updatedBy": { "type": "null" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "participantCount": { "type": "integer" }, "locationCount": { "type": "integer" } } } } } }, "example": { "items": [ { "_id": "671f2c…", "subsidiaryId": "sub_1789…_a1b2", "tenantId": "tnt_7Q2X…", "name": "Sample Trading", "legalName": "Sample Trading LLC", "code": "AE-HQ", "country": "AE", "taxRegistrationNumber": "1004****59", "netsuiteSubsidiaryId": "", "defaultCurrency": "AED", "status": "active", "isDefault": true, "sellerProfile": { "legalRegistrationId": "CN-12****7", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development", "address": { "streetName": "Sheikh Zayed Road", "cityName": "Dubai", "countrySubentity": "DXB", "postalZone": "00000" } }, "deletedAt": null, "createdBy": null, "updatedBy": null, "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-10-20T09:15:00.000Z", "participantCount": 2, "locationCount": 1 } ] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "post": { "operationId": "postTenantSubsidiaries", "summary": "Create a company", "description": "Creates a subsidiary (company) in the caller's tenant — the body cannot name another tenant. `code`, when given, must be unique among the tenant's companies (409 `SUBSIDIARY_CODE_TAKEN`). `isDefault: true` clears the previous default. `sellerProfile` is the seller identity used on the company's outbound invoices. Other refusals answer 400 `{ error: { code } }` (`NAME_REQUIRED`, `SUBSIDIARY_CONSTRAINT`, `TENANT_NOT_FOUND`). Audit-logged (`subsidiary.create`). Requires the `tenant_admin` role; a `tenant_user` gets 403.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Company & participants" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "legalName": { "type": "string" }, "code": { "type": "string" }, "country": { "type": "string", "maxLength": 2, "minLength": 2 }, "taxRegistrationNumber": { "type": "string" }, "netsuiteSubsidiaryId": { "type": "string" }, "defaultCurrency": { "type": "string" }, "isDefault": { "type": "boolean" }, "sellerProfile": { "type": "object", "properties": { "legalRegistrationId": { "type": "string" }, "legalRegistrationType": { "type": "string", "enum": [ "TL", "EID", "PAS", "CD" ] }, "legalRegistrationAuthorityName": { "type": "string" }, "address": { "type": "object", "properties": { "streetName": { "type": "string" }, "cityName": { "type": "string" }, "countrySubentity": { "type": "string" }, "postalZone": { "type": "string" } } } } } }, "required": [ "name" ] }, "example": { "name": "Sample Trading", "legalName": "Sample Trading LLC", "code": "AE-HQ", "country": "AE", "taxRegistrationNumber": "1004****59", "defaultCurrency": "AED", "isDefault": true, "sellerProfile": { "legalRegistrationId": "CN-12****7", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development", "address": { "streetName": "Sheikh Zayed Road", "cityName": "Dubai", "countrySubentity": "DXB", "postalZone": "00000" } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "subsidiary": { "type": "object", "properties": { "_id": { "type": "string" }, "subsidiaryId": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "legalName": { "type": "string" }, "code": { "type": "string" }, "country": { "type": "string" }, "taxRegistrationNumber": { "type": "string" }, "netsuiteSubsidiaryId": { "type": "string" }, "defaultCurrency": { "type": "string" }, "status": { "type": "string" }, "isDefault": { "type": "boolean" }, "sellerProfile": { "type": "object", "properties": { "legalRegistrationId": { "type": "string" }, "legalRegistrationType": { "type": "string" }, "legalRegistrationAuthorityName": { "type": "string" }, "address": { "type": "object", "properties": { "streetName": { "type": "string" }, "cityName": { "type": "string" }, "countrySubentity": { "type": "string" }, "postalZone": { "type": "string" } } } } }, "deletedAt": { "type": "null" }, "createdBy": { "type": "null" }, "updatedBy": { "type": "null" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } }, "example": { "ok": true, "subsidiary": { "_id": "671f2c…", "subsidiaryId": "sub_1789…_a1b2", "tenantId": "tnt_7Q2X…", "name": "Sample Trading", "legalName": "Sample Trading LLC", "code": "AE-HQ", "country": "AE", "taxRegistrationNumber": "1004****59", "netsuiteSubsidiaryId": "", "defaultCurrency": "AED", "status": "active", "isDefault": true, "sellerProfile": { "legalRegistrationId": "CN-12****7", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development", "address": { "streetName": "Sheikh Zayed Road", "cityName": "Dubai", "countrySubentity": "DXB", "postalZone": "00000" } }, "deletedAt": null, "createdBy": null, "updatedBy": null, "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-10-20T09:15:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "409": { "description": "The company code is already used (`SUBSIDIARY_CODE_TAKEN`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" } } } } }, "example": { "error": { "code": "SUBSIDIARY_CODE_TAKEN" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/peppol/validate": { "post": { "operationId": "postTenantPeppolValidate", "summary": "Validate a Peppol document with the session (sender resolved)", "description": "Same validation as `POST /api/integrations/peppol/validate`, with the user's session. `senderPeppolId` may be omitted: the server picks the tenant's default participant, else the first outbound-capable one, else the first one (participants with status `disabled` are ignored). A `senderPeppolId` that is not one of the tenant's participants answers 400, as does a tenant with no participant. Unlike `POST /api/tenant/invoices/validate`, no `tenant_user` allow-list check is applied.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Invoice sending" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inputType": { "type": "string" }, "environment": { "type": "string" }, "documentType": { "type": "string" }, "receiverPeppolId": { "type": "string" }, "payload": { "type": "object", "properties": { "invoiceNumber": { "type": "string" }, "issueDate": { "type": "string" }, "dueDate": { "type": "string" }, "currency": { "type": "string" }, "buyer": { "type": "object", "properties": { "name": { "type": "string" }, "peppolId": { "type": "string" } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "integer" }, "unitPrice": { "type": "integer" }, "vatCategory": { "type": "string" }, "vatRate": { "type": "integer" } } } } } } } }, "example": { "inputType": "json", "environment": "production", "documentType": "invoice", "receiverPeppolId": "0235:1002****03", "payload": { "invoiceNumber": "INV-2026-000123", "issueDate": "2026-10-20", "dueDate": "2026-11-19", "currency": "AED", "buyer": { "name": "Sample Buyer FZ-LLC", "peppolId": "0235:1002****03" }, "lines": [ { "description": "Consulting services", "quantity": 1, "unitPrice": 1000, "vatCategory": "S", "vatRate": 5 } ] } } } } }, "responses": { "200": { "description": "The document is valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "documentTypeId": { "type": "string" }, "processId": { "type": "string" }, "warnings": { "type": "array", "items": {} }, "phormSkipped": { "type": "boolean" }, "normalized": { "type": "object", "properties": { "sender": { "type": "string" }, "receiver": { "type": "string" }, "invoiceNumber": { "type": "string" }, "issueDate": { "type": "string" }, "currency": { "type": "string" }, "payableAmount": { "type": "integer" }, "invoiceTypeCode": { "type": "string" }, "dueDate": { "type": "string" }, "supplierName": { "type": "string" }, "customerName": { "type": "string" }, "netAmount": { "type": "integer" }, "taxAmount": { "type": "integer" } } } } }, "example": { "valid": true, "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "warnings": [], "phormSkipped": false, "normalized": { "sender": "0235:1004****59", "receiver": "0235:1002****03", "invoiceNumber": "INV-2026-000123", "issueDate": "2026-10-20", "currency": "AED", "payableAmount": 1050, "invoiceTypeCode": "380", "dueDate": "2026-11-19", "supplierName": "Sample Trading LLC", "customerName": "Sample Buyer FZ-LLC", "netAmount": 1000, "taxAmount": 50 } } } } }, "400": { "description": "The document failed validation, or the sender could not be resolved (standard error shape).", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "documentTypeId": { "type": "string" }, "processId": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "xpath": { "type": "string" } } } } } }, "warnings": { "type": "array", "items": {} } } }, "example": { "valid": false, "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "error": { "code": "PINT_VALIDATION_FAILED", "message": "Document failed Peppol/PINT validation.", "details": [ { "code": "ibr-144-ae", "message": "Buyer address must contain street, city and country subdivision.", "xpath": "/Invoice/cac:AccountingCustomerParty" } ] }, "warnings": [] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/peppol/invoices": { "post": { "operationId": "postTenantPeppolInvoices", "summary": "Submit a Peppol invoice with the session (sender resolved)", "description": "Same submission pipeline as `POST /api/integrations/peppol/invoices`, with the user's session and the sender resolved as in `POST /api/tenant/peppol/validate`. A non-empty `Idempotency-Key` header replaces `body.idempotencyKey` (no conflict check). No `tenant_user` allow-list check is applied. The `documents` links use the Integration API URLs.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Invoice sending" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional de-duplication key (1–120 characters), scoped to the tenant. A repeat with the same key returns the original transaction (`idempotent: true`) instead of sending again.", "schema": { "type": "string", "maxLength": 120, "example": "INV-2026-000123" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "inputType": { "type": "string" }, "environment": { "type": "string" }, "documentType": { "type": "string" }, "receiverPeppolId": { "type": "string" }, "payload": { "type": "object", "properties": { "invoiceNumber": { "type": "string" }, "issueDate": { "type": "string" }, "dueDate": { "type": "string" }, "currency": { "type": "string" }, "buyer": { "type": "object", "properties": { "name": { "type": "string" }, "peppolId": { "type": "string" } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "integer" }, "unitPrice": { "type": "integer" }, "vatCategory": { "type": "string" }, "vatRate": { "type": "integer" } } } } } } } }, "example": { "inputType": "json", "environment": "production", "documentType": "invoice", "receiverPeppolId": "0235:1002****03", "payload": { "invoiceNumber": "INV-2026-000123", "issueDate": "2026-10-20", "dueDate": "2026-11-19", "currency": "AED", "buyer": { "name": "Sample Buyer FZ-LLC", "peppolId": "0235:1002****03" }, "lines": [ { "description": "Consulting services", "quantity": 1, "unitPrice": 1000, "vatCategory": "S", "vatRate": 5 } ] } } } } }, "responses": { "202": { "description": "Accepted for Peppol delivery.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionId": { "type": "string" }, "status": { "type": "string" }, "valid": { "type": "boolean" }, "documentTypeId": { "type": "string" }, "processId": { "type": "string" }, "correlationId": { "type": "string" }, "as4MessageId": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "idempotent": { "type": "boolean" }, "warnings": { "type": "array", "items": {} }, "validatorPhormSkipped": { "type": "boolean" }, "documents": { "type": "object", "properties": { "invoiceXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "string" } } }, "invoicePdf": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "null" }, "fileName": { "type": "null" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "null" }, "reason": { "type": "string" } } }, "sbdXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "null" }, "fileName": { "type": "null" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "null" }, "reason": { "type": "string" } } }, "tddXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "null" }, "fileName": { "type": "null" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "null" }, "reason": { "type": "string" } } }, "mlsXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "null" }, "fileName": { "type": "null" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "null" }, "reason": { "type": "string" } } }, "payloadXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "privileged": { "type": "boolean" }, "requiredScope": { "type": "string" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "string" } } } } }, "message": { "type": "string" } } }, "example": { "transactionId": "txn_1789562400000_9f3a…", "status": "queued", "valid": true, "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "correlationId": "cor_1789562400000_4d5e…", "as4MessageId": "f0debc61-…@peppol.azdanapps.com", "sbdhInstanceId": "6c1d2e3f-…", "idempotent": false, "warnings": [], "validatorPhormSkipped": false, "documents": { "invoiceXml": { "available": true, "fileId": "file_01J9Z3…", "fileName": "txn_1789562400000_9f3a….xml", "contentType": "application/xml", "downloadUrl": "/api/integrations/peppol/transactions/txn_1789562400000_9f3a…/files/invoice-xml" }, "invoicePdf": { "available": false, "fileId": null, "fileName": null, "contentType": "application/pdf", "downloadUrl": null, "reason": "not_generated" }, "sbdXml": { "available": false, "fileId": null, "fileName": null, "contentType": "application/xml", "downloadUrl": null, "reason": "not_stored" }, "tddXml": { "available": false, "fileId": null, "fileName": null, "contentType": "application/xml", "downloadUrl": null, "reason": "not_generated" }, "mlsXml": { "available": false, "fileId": null, "fileName": null, "contentType": "application/xml", "downloadUrl": null, "reason": "not_received" }, "payloadXml": { "available": true, "privileged": true, "requiredScope": "peppol:payload:read", "contentType": "application/xml", "downloadUrl": "/api/integrations/peppol/transactions/txn_1789562400000_9f3a…/xml" } }, "message": "Invoice accepted for Peppol delivery." } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "422": { "$ref": "#/components/responses/ErrUnprocessable" }, "500": { "$ref": "#/components/responses/ErrInternal" }, "502": { "$ref": "#/components/responses/ErrBadGateway" }, "503": { "$ref": "#/components/responses/ErrUnavailable" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/integrations/netsuite": { "get": { "operationId": "getTenantIntegrationsNetsuite", "summary": "Get the NetSuite connection status", "description": "Returns the tenant's NetSuite connection without secrets: configuration, status (`not_configured`, `configured`, `connected`, `expired`, `reconnect_required`, `disconnected`), token expiry, account metadata and last test/delivery outcome. The client secret and tokens are reported only as `hasClientSecret` / `hasRefreshToken`. When nothing has been saved, only `configured: false, status: \"not_configured\"` is returned. Readable by any tenant user.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "responses": { "200": { "description": "Connection status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectionId": { "type": "string" }, "status": { "type": "string" }, "configured": { "type": "boolean" }, "connected": { "type": "boolean" }, "accountId": { "type": "string" }, "environment": { "type": "string" }, "restletUrl": { "type": "string" }, "scriptId": { "type": "string" }, "deployId": { "type": "string" }, "scopes": { "type": "string" }, "authType": { "type": "string" }, "clientId": { "type": "string" }, "hasClientSecret": { "type": "boolean" }, "keyId": { "type": "null" }, "hasRefreshToken": { "type": "boolean" }, "accessTokenExpiresAt": { "type": "string" }, "tokenExpiresAt": { "type": "string" }, "connectedAt": { "type": "string" }, "reconnectRequired": { "type": "boolean" }, "accountName": { "type": "string" }, "authorizedUser": { "type": "string" }, "authorizedRole": { "type": "string" }, "metadataFetchedAt": { "type": "string" }, "lastTokenRefreshAt": { "type": "string" }, "lastSuccessfulDeliveryAt": { "type": "string" }, "lastTestAt": { "type": "string" }, "lastTestOk": { "type": "boolean" }, "lastError": { "type": "null" }, "updatedAt": { "type": "string" } } }, "example": { "connectionId": "nsc_1729502043000_5e2d…", "status": "connected", "configured": true, "connected": true, "accountId": "1234567_SB1", "environment": "sandbox", "restletUrl": "https://1234567-sb1.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=…&deploy=1", "scriptId": "customscript_azdan_inbound", "deployId": "customdeploy_azdan_inbound", "scopes": "restlets", "authType": "oauth2_authorization_code", "clientId": "a3f9…", "hasClientSecret": true, "keyId": null, "hasRefreshToken": true, "accessTokenExpiresAt": "2026-10-21T10:14:03.000Z", "tokenExpiresAt": "2026-10-21T10:14:03.000Z", "connectedAt": "2026-10-21T09:14:03.000Z", "reconnectRequired": false, "accountName": "AZDAN Demo (Sandbox)", "authorizedUser": "o***@example.com", "authorizedRole": "Administrator", "metadataFetchedAt": "2026-10-21T09:14:03.000Z", "lastTokenRefreshAt": "2026-10-21T09:14:03.000Z", "lastSuccessfulDeliveryAt": "2026-10-20T16:40:00.000Z", "lastTestAt": "2026-10-21T09:14:41.000Z", "lastTestOk": true, "lastError": null, "updatedAt": "2026-10-21T09:14:41.000Z" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/integrations/netsuite/config": { "put": { "operationId": "putTenantIntegrationsNetsuiteConfig", "summary": "Save the NetSuite connection configuration", "description": "Saves the manual configuration (account id, environment, RESTlet / authorize / token URLs, script and deploy ids, scopes, client id, key id, client secret). Only fields sent are changed. URLs are checked against the SSRF rules. The client secret is AES-256-GCM encrypted at rest and is kept when the field is empty or omitted. Status moves from `not_configured` to `configured` once account id, client id and secret are present. tenant_admin only; audited.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "maxLength": 64 }, "environment": { "type": "string", "enum": [ "production", "sandbox" ] }, "restletUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "const": "", "type": "string" } ] }, "scriptId": { "type": "string", "maxLength": 64 }, "deployId": { "type": "string", "maxLength": 64 }, "scopes": { "type": "string", "maxLength": 256 }, "authorizeUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "const": "", "type": "string" } ] }, "tokenUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 2048 }, { "const": "", "type": "string" } ] }, "clientId": { "type": "string", "maxLength": 256 }, "clientSecret": { "type": "string", "maxLength": 2048 }, "keyId": { "type": "string", "maxLength": 256 } }, "additionalProperties": false }, "example": { "accountId": "1234567_SB1", "environment": "sandbox", "restletUrl": "https://1234567-sb1.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=…&deploy=1", "scriptId": "customscript_azdan_inbound", "deployId": "customdeploy_azdan_inbound", "scopes": "restlets", "clientId": "a3f9…", "clientSecret": "••••" } } } }, "responses": { "200": { "description": "The connection after saving.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectionId": { "type": "string" }, "status": { "type": "string" }, "configured": { "type": "boolean" }, "connected": { "type": "boolean" }, "accountId": { "type": "string" }, "environment": { "type": "string" }, "restletUrl": { "type": "string" }, "scriptId": { "type": "string" }, "deployId": { "type": "string" }, "scopes": { "type": "string" }, "authType": { "type": "string" }, "clientId": { "type": "string" }, "hasClientSecret": { "type": "boolean" }, "keyId": { "type": "null" }, "hasRefreshToken": { "type": "boolean" }, "accessTokenExpiresAt": { "type": "null" }, "tokenExpiresAt": { "type": "null" }, "connectedAt": { "type": "null" }, "reconnectRequired": { "type": "boolean" }, "accountName": { "type": "null" }, "authorizedUser": { "type": "null" }, "authorizedRole": { "type": "null" }, "metadataFetchedAt": { "type": "null" }, "lastTokenRefreshAt": { "type": "null" }, "lastSuccessfulDeliveryAt": { "type": "string" }, "lastTestAt": { "type": "string" }, "lastTestOk": { "type": "boolean" }, "lastError": { "type": "null" }, "updatedAt": { "type": "string" } } }, "example": { "connectionId": "nsc_1729502043000_5e2d…", "status": "configured", "configured": true, "connected": false, "accountId": "1234567_SB1", "environment": "sandbox", "restletUrl": "https://1234567-sb1.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=…&deploy=1", "scriptId": "customscript_azdan_inbound", "deployId": "customdeploy_azdan_inbound", "scopes": "restlets", "authType": "oauth2_authorization_code", "clientId": "a3f9…", "hasClientSecret": true, "keyId": null, "hasRefreshToken": false, "accessTokenExpiresAt": null, "tokenExpiresAt": null, "connectedAt": null, "reconnectRequired": false, "accountName": null, "authorizedUser": null, "authorizedRole": null, "metadataFetchedAt": null, "lastTokenRefreshAt": null, "lastSuccessfulDeliveryAt": "2026-10-20T16:40:00.000Z", "lastTestAt": "2026-10-21T09:14:41.000Z", "lastTestOk": true, "lastError": null, "updatedAt": "2026-10-21T09:14:41.000Z" } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/integrations/netsuite/oauth/start": { "post": { "operationId": "postTenantIntegrationsNetsuiteOauthStart", "summary": "Start the NetSuite OAuth authorization", "description": "Begins the OAuth 2.0 authorization-code flow: stores a one-time `state` (valid 10 minutes, bound to tenant, user, connection, environment and account) and returns the NetSuite authorize URL to open in the browser. The redirect URI comes from server configuration (`NETSUITE_OAUTH_REDIRECT_URI` or the tenant portal origin); a `redirectUri` in the body is accepted but not used. tenant_admin only; audited.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectUri": { "type": "string", "format": "uri", "maxLength": 2048 } }, "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Authorize URL and state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorizeUrl": { "type": "string" }, "state": { "type": "string" }, "redirectUri": { "type": "string" } } }, "example": { "authorizeUrl": "https://1234567-sb1.app.netsuite.com/app/login/oauth2/authorize.nl?response_type=code&client_id=a3f9…&redirect_uri=…&scope=restlets&state=9d1e…", "state": "9d1e…", "redirectUri": "https://portal.example.com/portal/integrations/netsuite/callback" } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "409": { "$ref": "#/components/responses/ErrConflict" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/integrations/netsuite/oauth/callback": { "post": { "operationId": "postTenantIntegrationsNetsuiteOauthCallback", "summary": "Complete the NetSuite OAuth authorization", "description": "Completes the flow with the `state` and `code` NetSuite returned. The state must match, be unexpired and belong to the same tenant, user, connection, environment and account. The code is exchanged server-side using the stored redirect URI; tokens are stored encrypted and account metadata is fetched from NetSuite's userinfo endpoint (falling back to `company` / `entity` / `role` from the body). The one-time state is cleared either way. A NetSuite `error` sets status back to `configured`; a failed exchange sets `reconnect_required`. A `redirectUri` in the body is not used. tenant_admin only; audited.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "minLength": 1, "maxLength": 128 }, "code": { "type": "string", "minLength": 1, "maxLength": 4096 }, "redirectUri": { "type": "string", "format": "uri", "maxLength": 2048 }, "error": { "type": "string", "maxLength": 256 }, "role": { "type": "string", "maxLength": 256 }, "entity": { "type": "string", "maxLength": 256 }, "company": { "type": "string", "maxLength": 512 } }, "additionalProperties": false }, "example": { "state": "9d1e…", "code": "••••", "company": "AZDAN Demo (Sandbox)", "role": "3", "entity": "-5" } } } }, "responses": { "200": { "description": "The connected connection.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectionId": { "type": "string" }, "status": { "type": "string" }, "configured": { "type": "boolean" }, "connected": { "type": "boolean" }, "accountId": { "type": "string" }, "environment": { "type": "string" }, "restletUrl": { "type": "string" }, "scriptId": { "type": "string" }, "deployId": { "type": "string" }, "scopes": { "type": "string" }, "authType": { "type": "string" }, "clientId": { "type": "string" }, "hasClientSecret": { "type": "boolean" }, "keyId": { "type": "null" }, "hasRefreshToken": { "type": "boolean" }, "accessTokenExpiresAt": { "type": "string" }, "tokenExpiresAt": { "type": "string" }, "connectedAt": { "type": "string" }, "reconnectRequired": { "type": "boolean" }, "accountName": { "type": "string" }, "authorizedUser": { "type": "string" }, "authorizedRole": { "type": "string" }, "metadataFetchedAt": { "type": "string" }, "lastTokenRefreshAt": { "type": "string" }, "lastSuccessfulDeliveryAt": { "type": "string" }, "lastTestAt": { "type": "string" }, "lastTestOk": { "type": "boolean" }, "lastError": { "type": "null" }, "updatedAt": { "type": "string" } } }, "example": { "connectionId": "nsc_1729502043000_5e2d…", "status": "connected", "configured": true, "connected": true, "accountId": "1234567_SB1", "environment": "sandbox", "restletUrl": "https://1234567-sb1.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=…&deploy=1", "scriptId": "customscript_azdan_inbound", "deployId": "customdeploy_azdan_inbound", "scopes": "restlets", "authType": "oauth2_authorization_code", "clientId": "a3f9…", "hasClientSecret": true, "keyId": null, "hasRefreshToken": true, "accessTokenExpiresAt": "2026-10-21T10:14:03.000Z", "tokenExpiresAt": "2026-10-21T10:14:03.000Z", "connectedAt": "2026-10-21T09:14:03.000Z", "reconnectRequired": false, "accountName": "AZDAN Demo (Sandbox)", "authorizedUser": "o***@example.com", "authorizedRole": "Administrator", "metadataFetchedAt": "2026-10-21T09:14:03.000Z", "lastTokenRefreshAt": "2026-10-21T09:14:03.000Z", "lastSuccessfulDeliveryAt": "2026-10-20T16:40:00.000Z", "lastTestAt": "2026-10-21T09:14:41.000Z", "lastTestOk": true, "lastError": null, "updatedAt": "2026-10-21T09:14:41.000Z" } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "409": { "$ref": "#/components/responses/ErrConflict" }, "500": { "$ref": "#/components/responses/ErrInternal" }, "502": { "$ref": "#/components/responses/ErrBadGateway" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/integrations/netsuite/test": { "post": { "operationId": "postTenantIntegrationsNetsuiteTest", "summary": "Test the NetSuite connection", "description": "Checks that a valid access token can be obtained, refreshing it when it is close to expiry. Records `lastTestAt` / `lastTestOk` (and `lastError` on failure) on the connection. A failed check is HTTP 200 with `ok: false` and a code such as `DISCONNECTED`, `NETSUITE_TOKEN_REFRESH_FAILED` or `DECRYPT_FAILED`. tenant_admin only; audited.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "Test result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "code": { "type": "string" }, "status": { "type": "string" }, "connection": { "type": "object", "properties": { "connectionId": { "type": "string" }, "status": { "type": "string" }, "configured": { "type": "boolean" }, "connected": { "type": "boolean" }, "accountId": { "type": "string" }, "environment": { "type": "string" }, "restletUrl": { "type": "string" }, "scriptId": { "type": "string" }, "deployId": { "type": "string" }, "scopes": { "type": "string" }, "authType": { "type": "string" }, "clientId": { "type": "string" }, "hasClientSecret": { "type": "boolean" }, "keyId": { "type": "null" }, "hasRefreshToken": { "type": "boolean" }, "accessTokenExpiresAt": { "type": "string" }, "tokenExpiresAt": { "type": "string" }, "connectedAt": { "type": "string" }, "reconnectRequired": { "type": "boolean" }, "accountName": { "type": "string" }, "authorizedUser": { "type": "string" }, "authorizedRole": { "type": "string" }, "metadataFetchedAt": { "type": "string" }, "lastTokenRefreshAt": { "type": "string" }, "lastSuccessfulDeliveryAt": { "type": "string" }, "lastTestAt": { "type": "string" }, "lastTestOk": { "type": "boolean" }, "lastError": { "type": "null" }, "updatedAt": { "type": "string" } } } } }, "example": { "ok": true, "code": "ok", "status": "connected", "connection": { "connectionId": "nsc_1729502043000_5e2d…", "status": "connected", "configured": true, "connected": true, "accountId": "1234567_SB1", "environment": "sandbox", "restletUrl": "https://1234567-sb1.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=…&deploy=1", "scriptId": "customscript_azdan_inbound", "deployId": "customdeploy_azdan_inbound", "scopes": "restlets", "authType": "oauth2_authorization_code", "clientId": "a3f9…", "hasClientSecret": true, "keyId": null, "hasRefreshToken": true, "accessTokenExpiresAt": "2026-10-21T10:14:03.000Z", "tokenExpiresAt": "2026-10-21T10:14:03.000Z", "connectedAt": "2026-10-21T09:14:03.000Z", "reconnectRequired": false, "accountName": "AZDAN Demo (Sandbox)", "authorizedUser": "o***@example.com", "authorizedRole": "Administrator", "metadataFetchedAt": "2026-10-21T09:14:03.000Z", "lastTokenRefreshAt": "2026-10-21T09:14:03.000Z", "lastSuccessfulDeliveryAt": "2026-10-20T16:40:00.000Z", "lastTestAt": "2026-10-21T09:14:41.000Z", "lastTestOk": true, "lastError": null, "updatedAt": "2026-10-21T09:14:41.000Z" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "409": { "$ref": "#/components/responses/ErrConflict" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/integrations/netsuite/disconnect": { "post": { "operationId": "postTenantIntegrationsNetsuiteDisconnect", "summary": "Disconnect NetSuite", "description": "Deletes the stored access and refresh tokens and any pending OAuth state, and sets status `disconnected`. The saved configuration and client secret are kept, so the tenant can reconnect with `oauth/start`. When no connection exists, returns `{ ok: true, status: \"not_configured\" }`. Tokens are not revoked at NetSuite. tenant_admin only; audited.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "Disconnected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string" }, "connection": { "type": "object", "properties": { "connectionId": { "type": "string" }, "status": { "type": "string" }, "configured": { "type": "boolean" }, "connected": { "type": "boolean" }, "accountId": { "type": "string" }, "environment": { "type": "string" }, "restletUrl": { "type": "string" }, "scriptId": { "type": "string" }, "deployId": { "type": "string" }, "scopes": { "type": "string" }, "authType": { "type": "string" }, "clientId": { "type": "string" }, "hasClientSecret": { "type": "boolean" }, "keyId": { "type": "null" }, "hasRefreshToken": { "type": "boolean" }, "accessTokenExpiresAt": { "type": "null" }, "tokenExpiresAt": { "type": "null" }, "connectedAt": { "type": "string" }, "reconnectRequired": { "type": "boolean" }, "accountName": { "type": "string" }, "authorizedUser": { "type": "string" }, "authorizedRole": { "type": "string" }, "metadataFetchedAt": { "type": "string" }, "lastTokenRefreshAt": { "type": "string" }, "lastSuccessfulDeliveryAt": { "type": "string" }, "lastTestAt": { "type": "string" }, "lastTestOk": { "type": "boolean" }, "lastError": { "type": "null" }, "updatedAt": { "type": "string" } } } } }, "example": { "ok": true, "status": "disconnected", "connection": { "connectionId": "nsc_1729502043000_5e2d…", "status": "disconnected", "configured": true, "connected": false, "accountId": "1234567_SB1", "environment": "sandbox", "restletUrl": "https://1234567-sb1.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=…&deploy=1", "scriptId": "customscript_azdan_inbound", "deployId": "customdeploy_azdan_inbound", "scopes": "restlets", "authType": "oauth2_authorization_code", "clientId": "a3f9…", "hasClientSecret": true, "keyId": null, "hasRefreshToken": false, "accessTokenExpiresAt": null, "tokenExpiresAt": null, "connectedAt": "2026-10-21T09:14:03.000Z", "reconnectRequired": false, "accountName": "AZDAN Demo (Sandbox)", "authorizedUser": "o***@example.com", "authorizedRole": "Administrator", "metadataFetchedAt": "2026-10-21T09:14:03.000Z", "lastTokenRefreshAt": "2026-10-21T09:14:03.000Z", "lastSuccessfulDeliveryAt": "2026-10-20T16:40:00.000Z", "lastTestAt": "2026-10-21T09:14:41.000Z", "lastTestOk": true, "lastError": null, "updatedAt": "2026-10-21T09:14:41.000Z" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/users": { "get": { "operationId": "getTenantUsers", "summary": "List the tenant's users", "description": "All users of the caller's tenant, newest first, with safe fields only (no password hash or MFA secrets). Requires the `tenant_admin` role; a `tenant_user` gets 403.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Users & API keys" ], "responses": { "200": { "description": "The users.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "userId": { "type": "string" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "role": { "type": "string" }, "tenantId": { "type": "string" }, "allowedSubsidiaryIds": { "type": "array", "items": { "type": "string" } }, "allowedPeppolParticipantIds": { "type": "array", "items": {} }, "status": { "type": "string" }, "mfaEnabled": { "type": "boolean" }, "lastLoginAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } } }, "example": { "items": [ { "_id": "671f5c…", "userId": "user_1789562400000_5e6f…", "email": "o***@example.com", "displayName": "Finance operator", "role": "tenant_user", "tenantId": "tnt_7Q2X…", "allowedSubsidiaryIds": [ "sub_1789…_a1b2" ], "allowedPeppolParticipantIds": [], "status": "active", "mfaEnabled": false, "lastLoginAt": "2026-10-23T06:10:00.000Z", "createdAt": "2026-09-10T12:00:00.000Z", "updatedAt": "2026-10-20T08:00:00.000Z" } ] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "post": { "operationId": "postTenantUsers", "summary": "Create a tenant user", "description": "Creates an active `tenant_admin` or `tenant_user` in the caller's tenant. The email is lower-cased and must be unused platform-wide (409 `USER_EXISTS`). `allowedSubsidiaryIds` is silently reduced to companies of this tenant. A server-generated temporary password is returned **once** in `tempPassword`; only its bcrypt hash is stored. Audit-logged (`user.create`). Requires the `tenant_admin` role; a `tenant_user` gets 403.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Users & API keys" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 200 }, "role": { "type": "string", "enum": [ "tenant_admin", "tenant_user", "tenant_developer", "tenant_viewer" ] }, "displayName": { "type": "string", "maxLength": 120 }, "allowedSubsidiaryIds": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "maxItems": 50 } }, "required": [ "email", "role" ], "additionalProperties": false }, "example": { "email": "o***@example.com", "role": "tenant_user", "displayName": "Finance operator", "allowedSubsidiaryIds": [ "sub_1789…_a1b2" ] } } } }, "responses": { "201": { "description": "Created. The temporary password is shown only in this response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "user": { "type": "object", "properties": { "_id": { "type": "string" }, "userId": { "type": "string" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "role": { "type": "string" }, "tenantId": { "type": "string" }, "allowedSubsidiaryIds": { "type": "array", "items": { "type": "string" } }, "allowedPeppolParticipantIds": { "type": "array", "items": {} }, "status": { "type": "string" }, "mfaEnabled": { "type": "boolean" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "tokenVersion": { "type": "integer" }, "activation": { "type": "object", "properties": { "tokenHash": { "type": "null" }, "expiresAt": { "type": "null" }, "sentAt": { "type": "null" }, "usedAt": { "type": "null" } } } } }, "tempPassword": { "type": "string" } } }, "example": { "ok": true, "user": { "_id": "671f5c…", "userId": "user_1789562400000_5e6f…", "email": "o***@example.com", "displayName": "Finance operator", "role": "tenant_user", "tenantId": "tnt_7Q2X…", "allowedSubsidiaryIds": [ "sub_1789…_a1b2" ], "allowedPeppolParticipantIds": [], "status": "active", "mfaEnabled": false, "createdAt": "2026-09-10T12:00:00.000Z", "updatedAt": "2026-10-20T08:00:00.000Z", "tokenVersion": 0, "activation": { "tokenHash": null, "expiresAt": null, "sentAt": null, "usedAt": null } }, "tempPassword": "Xk7#…(16 chars)" } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "409": { "$ref": "#/components/responses/ErrConflict" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/users/{userId}": { "patch": { "operationId": "patchTenantUsersByUserId", "summary": "Update a tenant user's role, name or company access", "description": "Updates `role`, `displayName` (blank resets it to the email) and/or `allowedSubsidiaryIds` (reduced to this tenant's companies) of a user in the caller's tenant. An admin cannot change their own role (409 `CANNOT_CHANGE_OWN_ROLE`). Audit-logged (`user.update`). Requires the `tenant_admin` role; a `tenant_user` gets 403.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Users & API keys" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "tenant_admin", "tenant_user", "tenant_developer", "tenant_viewer" ] }, "displayName": { "type": "string", "maxLength": 120 }, "allowedSubsidiaryIds": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "maxItems": 50 } }, "additionalProperties": false }, "example": { "role": "tenant_user", "allowedSubsidiaryIds": [ "sub_1789…_a1b2" ] } } } }, "responses": { "200": { "description": "The updated user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "user": { "type": "object", "properties": { "_id": { "type": "string" }, "userId": { "type": "string" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "role": { "type": "string" }, "tenantId": { "type": "string" }, "allowedSubsidiaryIds": { "type": "array", "items": { "type": "string" } }, "allowedPeppolParticipantIds": { "type": "array", "items": {} }, "status": { "type": "string" }, "mfaEnabled": { "type": "boolean" }, "lastLoginAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } }, "example": { "ok": true, "user": { "_id": "671f5c…", "userId": "user_1789562400000_5e6f…", "email": "o***@example.com", "displayName": "Finance operator", "role": "tenant_user", "tenantId": "tnt_7Q2X…", "allowedSubsidiaryIds": [ "sub_1789…_a1b2" ], "allowedPeppolParticipantIds": [], "status": "active", "mfaEnabled": false, "lastLoginAt": "2026-10-23T06:10:00.000Z", "createdAt": "2026-09-10T12:00:00.000Z", "updatedAt": "2026-10-20T08:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "409": { "$ref": "#/components/responses/ErrConflict" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/users/{userId}/status": { "patch": { "operationId": "patchTenantUsersByUserIdStatus", "summary": "Activate or disable a tenant user", "description": "Sets `status` to `active` or `disabled`. Disabling revokes the user's sessions immediately. An admin cannot change their own status (409 `CANNOT_CHANGE_OWN_STATUS`). Audit-logged (`user.activate` / `user.deactivate`). Requires the `tenant_admin` role; a `tenant_user` gets 403.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Users & API keys" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "disabled" ] } }, "required": [ "status" ], "additionalProperties": false }, "example": { "status": "disabled" } } } }, "responses": { "200": { "description": "The updated user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "user": { "type": "object", "properties": { "_id": { "type": "string" }, "userId": { "type": "string" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "role": { "type": "string" }, "tenantId": { "type": "string" }, "allowedSubsidiaryIds": { "type": "array", "items": { "type": "string" } }, "allowedPeppolParticipantIds": { "type": "array", "items": {} }, "status": { "type": "string" }, "mfaEnabled": { "type": "boolean" }, "lastLoginAt": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } }, "example": { "ok": true, "user": { "_id": "671f5c…", "userId": "user_1789562400000_5e6f…", "email": "o***@example.com", "displayName": "Finance operator", "role": "tenant_user", "tenantId": "tnt_7Q2X…", "allowedSubsidiaryIds": [ "sub_1789…_a1b2" ], "allowedPeppolParticipantIds": [], "status": "disabled", "mfaEnabled": false, "lastLoginAt": "2026-10-23T06:10:00.000Z", "createdAt": "2026-09-10T12:00:00.000Z", "updatedAt": "2026-10-20T08:00:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "409": { "$ref": "#/components/responses/ErrConflict" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/users/{userId}/reset-password": { "post": { "operationId": "postTenantUsersByUserIdResetPassword", "summary": "Reset a tenant user's password", "description": "Replaces the user's password with a new server-generated temporary password, returned **once** in `tempPassword`, and revokes their sessions. An admin cannot reset their own password here (409 `CANNOT_RESET_OWN_PASSWORD`). Audit-logged (`user.password_reset`). Requires the `tenant_admin` role; a `tenant_user` gets 403.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Users & API keys" ], "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "The new temporary password, shown only in this response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "tempPassword": { "type": "string" } } }, "example": { "ok": true, "tempPassword": "Pq9=…(16 chars)" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "409": { "$ref": "#/components/responses/ErrConflict" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/mappings": { "get": { "operationId": "getTenantMappings", "summary": "List field mappings", "description": "Lists the tenant's ERP-to-PINT field mappings, most recently updated first, as a bare array of summaries (not paginated). Readable by any tenant user.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Mappings" ], "responses": { "200": { "description": "Mapping summaries.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sourceSystem": { "type": "string" }, "docType": { "type": "string" }, "activeVersion": { "type": "integer" }, "versionCount": { "type": "integer" }, "updatedAt": { "type": "string" } } } }, "example": [ { "id": "map_1729502043000_7a1c…", "name": "NetSuite invoices", "sourceSystem": "netsuite", "docType": "invoice", "activeVersion": 1, "versionCount": 2, "updatedAt": "2026-10-21T09:14:03.000Z" } ] } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "post": { "operationId": "postTenantMappings", "summary": "Create a field mapping", "description": "Creates a mapping with version 1 as a Draft. With a `sampleRecord`, the source schema is inferred from it, connections are auto-suggested by field-name synonyms and the record is stored as the first sample; without one the draft is empty. `docType` defaults to `invoice`, `sourceSystem` to `custom`. `tenant_admin` only; audited.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Mappings" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "docType": { "type": "string", "enum": [ "invoice", "creditNote" ] }, "sourceSystem": { "type": "string", "maxLength": 60 }, "sampleRecord": { "type": "object", "additionalProperties": {} }, "sampleLabel": { "type": "string", "maxLength": 120 } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "NetSuite invoices", "docType": "invoice", "sourceSystem": "netsuite", "sampleLabel": "Gulf Trading", "sampleRecord": { "tranid": "INV-1042", "trandate": "2026-10-20", "item": [ { "amount": 450, "taxcode": "VAT_AE:S" } ] } } } } }, "responses": { "201": { "description": "The created mapping.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sourceSystem": { "type": "string" }, "docType": { "type": "string" }, "activeVersion": { "type": "null" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "status": { "type": "string" }, "author": { "type": "string" }, "date": { "type": "string" }, "note": { "type": "string" }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" }, "transform": { "type": "object", "properties": { "type": { "type": "string" } } } } } } } } }, "sourceSchema": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "repeating": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } } } } } } }, "targetSchema": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "required": { "type": "boolean" } } } } } } } } }, "example": { "id": "map_1729502043000_7a1c…", "name": "NetSuite invoices", "sourceSystem": "netsuite", "docType": "invoice", "activeVersion": null, "versions": [ { "version": 1, "status": "Draft", "author": "o***@example.com", "date": "2026-10-21T09:14:03.000Z", "note": "Auto-mapped from sample record.", "connections": [ { "id": "c1", "source": "header.tranid", "target": "invoiceNumber", "transform": { "type": "direct" } }, { "id": "c2", "source": "header.trandate", "target": "issueDate", "transform": { "type": "direct" } }, { "id": "c3", "source": "item[].taxcode", "target": "lines[].taxCategory", "transform": { "type": "lookup", "pairs": [ { "from": "VAT_AE:S", "to": "S" }, { "from": "VAT_AE:Z", "to": "Z" } ] } } ] } ], "sourceSchema": [ { "key": "header", "label": "Header", "repeating": false, "fields": [ { "id": "tranid", "type": "text" }, { "id": "trandate", "type": "date" } ] }, { "key": "item", "label": "item", "repeating": true, "fields": [ { "id": "item[].amount", "type": "number" }, { "id": "item[].taxcode", "type": "text" } ] } ], "targetSchema": [ { "key": "document", "label": "Document", "fields": [ { "id": "invoiceNumber", "type": "text", "required": true }, { "id": "issueDate", "type": "date", "required": true }, { "id": "currency", "type": "text", "required": false, "defaultValue": "AED" } ] }, { "key": "supplier", "label": "Supplier", "derived": true, "fields": [] } ] } } } }, "400": { "description": "Rejected by a mapping rule. The body carries only `error.code` (no `message`), plus `unmapped` or `issues` where relevant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" } } } } }, "example": { "error": { "code": "SAMPLE_EMPTY" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/mappings/{mappingId}": { "get": { "operationId": "getTenantMappingsByMappingId", "summary": "Get a field mapping", "description": "Returns a mapping with all its versions (connections included), the inferred source schema and the PINT target schema for its document type.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Mappings" ], "parameters": [ { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The mapping.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "sourceSystem": { "type": "string" }, "docType": { "type": "string" }, "activeVersion": { "type": "integer" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "status": { "type": "string" }, "author": { "type": "string" }, "date": { "type": "string" }, "note": { "type": "string" }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" }, "transform": { "type": "object", "properties": { "type": { "type": "string" } } } } } } } } }, "sourceSchema": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "repeating": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } } } } } } }, "targetSchema": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "required": { "type": "boolean" } } } } } } } } }, "example": { "id": "map_1729502043000_7a1c…", "name": "NetSuite invoices", "sourceSystem": "netsuite", "docType": "invoice", "activeVersion": 1, "versions": [ { "version": 1, "status": "Active", "author": "o***@example.com", "date": "2026-10-01T08:00:00.000Z", "note": "Go-live (approved by Finance lead)", "connections": [ { "id": "c1", "source": "header.tranid", "target": "invoiceNumber", "transform": { "type": "direct" } }, { "id": "c2", "source": "header.trandate", "target": "issueDate", "transform": { "type": "direct" } }, { "id": "c3", "source": "item[].taxcode", "target": "lines[].taxCategory", "transform": { "type": "lookup", "pairs": [ { "from": "VAT_AE:S", "to": "S" }, { "from": "VAT_AE:Z", "to": "Z" } ] } } ] }, { "version": 2, "status": "Draft", "author": "o***@example.com", "date": "2026-10-21T09:14:03.000Z", "note": "Draft in progress.", "connections": [ { "id": "c1", "source": "header.tranid", "target": "invoiceNumber", "transform": { "type": "direct" } }, { "id": "c2", "source": "header.trandate", "target": "issueDate", "transform": { "type": "direct" } }, { "id": "c3", "source": "item[].taxcode", "target": "lines[].taxCategory", "transform": { "type": "lookup", "pairs": [ { "from": "VAT_AE:S", "to": "S" }, { "from": "VAT_AE:Z", "to": "Z" } ] } } ] } ], "sourceSchema": [ { "key": "header", "label": "Header", "repeating": false, "fields": [ { "id": "tranid", "type": "text" }, { "id": "trandate", "type": "date" } ] }, { "key": "item", "label": "item", "repeating": true, "fields": [ { "id": "item[].amount", "type": "number" }, { "id": "item[].taxcode", "type": "text" } ] } ], "targetSchema": [ { "key": "document", "label": "Document", "fields": [ { "id": "invoiceNumber", "type": "text", "required": true }, { "id": "issueDate", "type": "date", "required": true }, { "id": "currency", "type": "text", "required": false, "defaultValue": "AED" } ] }, { "key": "supplier", "label": "Supplier", "derived": true, "fields": [] } ] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/mappings/{mappingId}/versions": { "get": { "operationId": "getTenantMappingsByMappingIdVersions", "summary": "List a mapping's versions", "description": "Returns the mapping's versions as a bare array (Draft, Active, Archived), each with author, date, note and connections.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Mappings" ], "parameters": [ { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Versions.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "status": { "type": "string" }, "author": { "type": "string" }, "date": { "type": "string" }, "note": { "type": "string" }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" }, "transform": { "type": "object", "properties": { "type": { "type": "string" } } } } } } } } }, "example": [ { "version": 1, "status": "Active", "author": "o***@example.com", "date": "2026-10-01T08:00:00.000Z", "note": "Go-live (approved by Finance lead)", "connections": [ { "id": "c1", "source": "header.tranid", "target": "invoiceNumber", "transform": { "type": "direct" } }, { "id": "c2", "source": "header.trandate", "target": "issueDate", "transform": { "type": "direct" } }, { "id": "c3", "source": "item[].taxcode", "target": "lines[].taxCategory", "transform": { "type": "lookup", "pairs": [ { "from": "VAT_AE:S", "to": "S" }, { "from": "VAT_AE:Z", "to": "Z" } ] } } ] }, { "version": 2, "status": "Draft", "author": "o***@example.com", "date": "2026-10-21T09:14:03.000Z", "note": "Draft in progress.", "connections": [ { "id": "c1", "source": "header.tranid", "target": "invoiceNumber", "transform": { "type": "direct" } }, { "id": "c2", "source": "header.trandate", "target": "issueDate", "transform": { "type": "direct" } }, { "id": "c3", "source": "item[].taxcode", "target": "lines[].taxCategory", "transform": { "type": "lookup", "pairs": [ { "from": "VAT_AE:S", "to": "S" }, { "from": "VAT_AE:Z", "to": "Z" } ] } } ] } ] } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/mappings/{mappingId}/samples": { "get": { "operationId": "getTenantMappingsByMappingIdSamples", "summary": "List a mapping's sample records", "description": "Returns the stored sample ERP records (at most 10) as a bare array, each with its id, counterparty label and the full record.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Mappings" ], "parameters": [ { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Samples.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "counterparty": { "type": "string" }, "record": { "type": "object", "properties": { "tranid": { "type": "string" }, "trandate": { "type": "string" }, "item": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "integer" }, "taxcode": { "type": "string" } } } } } } } } }, "example": [ { "id": "sample_1729502043000_0b9e…", "counterparty": "Gulf Trading", "record": { "tranid": "INV-1042", "trandate": "2026-10-20", "item": [ { "amount": 450, "taxcode": "VAT_AE:S" } ] } } ] } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "post": { "operationId": "postTenantMappingsByMappingIdSamples", "summary": "Add a sample record to a mapping", "description": "Stores another sample ERP record (maximum 10 per mapping) and merges any new source fields it reveals into the source schema. `tenant_admin` only; audited.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Mappings" ], "parameters": [ { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "counterparty": { "type": "string", "maxLength": 120 }, "record": { "type": "object", "additionalProperties": {} } }, "required": [ "record" ], "additionalProperties": false }, "example": { "counterparty": "Gulf Trading", "record": { "tranid": "INV-1042", "trandate": "2026-10-20", "item": [ { "amount": 450, "taxcode": "VAT_AE:S" } ] } } } } }, "responses": { "201": { "description": "The stored sample and the merged source schema.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sample": { "type": "object", "properties": { "id": { "type": "string" }, "counterparty": { "type": "string" }, "record": { "type": "object", "properties": { "tranid": { "type": "string" }, "trandate": { "type": "string" }, "item": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "integer" }, "taxcode": { "type": "string" } } } } } } } }, "sourceSchema": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "repeating": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } } } } } } } } }, "example": { "sample": { "id": "sample_1729502043000_0b9e…", "counterparty": "Gulf Trading", "record": { "tranid": "INV-1042", "trandate": "2026-10-20", "item": [ { "amount": 450, "taxcode": "VAT_AE:S" } ] } }, "sourceSchema": [ { "key": "header", "label": "Header", "repeating": false, "fields": [ { "id": "tranid", "type": "text" }, { "id": "trandate", "type": "date" } ] }, { "key": "item", "label": "item", "repeating": true, "fields": [ { "id": "item[].amount", "type": "number" }, { "id": "item[].taxcode", "type": "text" } ] } ] } } } }, "400": { "description": "Rejected by a mapping rule. The body carries only `error.code` (no `message`), plus `unmapped` or `issues` where relevant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" } } } } }, "example": { "error": { "code": "SAMPLE_LIMIT" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/mappings/{mappingId}/draft": { "put": { "operationId": "putTenantMappingsByMappingIdDraft", "summary": "Save a mapping draft", "description": "Replaces the connections of the mapping's Draft version, creating a new Draft (next version number) when none exists. Connections are checked structurally first; blocking issues (`MAP_MALFORMED_CONNECTION`, `MAP_DUPLICATE_TARGET`, `MAP_BAD_FORMULA`) return 400 with `issues`. The Draft never runs in the submission path. `tenant_admin` only. Not audited.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Mappings" ], "parameters": [ { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 80 }, "source": { "type": "string", "maxLength": 300 }, "target": { "type": "string", "maxLength": 300 }, "transform": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "direct", "formula", "lookup", "conditional" ] }, "expression": { "type": "string", "maxLength": 500 }, "pairs": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "maxLength": 200 }, "to": { "type": "string", "maxLength": 200 } }, "required": [ "from", "to" ] }, "maxItems": 100 }, "field": { "type": "string", "maxLength": 200 }, "value": { "type": "string", "maxLength": 200 }, "then": { "type": "string", "maxLength": 200 }, "else": { "type": "string", "maxLength": 200 } }, "required": [ "type" ], "additionalProperties": false } }, "required": [ "id", "source", "target" ], "additionalProperties": false }, "maxItems": 200 } }, "required": [ "connections" ], "additionalProperties": false }, "example": { "connections": [ { "id": "c1", "source": "header.tranid", "target": "invoiceNumber", "transform": { "type": "direct" } }, { "id": "c2", "source": "header.trandate", "target": "issueDate", "transform": { "type": "direct" } }, { "id": "c3", "source": "item[].taxcode", "target": "lines[].taxCategory", "transform": { "type": "lookup", "pairs": [ { "from": "VAT_AE:S", "to": "S" }, { "from": "VAT_AE:Z", "to": "Z" } ] } } ] } } } }, "responses": { "200": { "description": "The saved Draft version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "object", "properties": { "version": { "type": "integer" }, "status": { "type": "string" }, "author": { "type": "string" }, "date": { "type": "string" }, "note": { "type": "string" }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" }, "transform": { "type": "object", "properties": { "type": { "type": "string" } } } } } } } } } }, "example": { "version": { "version": 2, "status": "Draft", "author": "o***@example.com", "date": "2026-10-21T09:14:03.000Z", "note": "Draft in progress.", "connections": [ { "id": "c1", "source": "header.tranid", "target": "invoiceNumber", "transform": { "type": "direct" } }, { "id": "c2", "source": "header.trandate", "target": "issueDate", "transform": { "type": "direct" } }, { "id": "c3", "source": "item[].taxcode", "target": "lines[].taxCategory", "transform": { "type": "lookup", "pairs": [ { "from": "VAT_AE:S", "to": "S" }, { "from": "VAT_AE:Z", "to": "Z" } ] } } ] } } } } }, "400": { "description": "Rejected by a mapping rule. The body carries only `error.code` (no `message`), plus `unmapped` or `issues` where relevant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string" }, "targetPath": { "type": "string" }, "sourceField": { "type": "string" } } } } } } } }, "example": { "error": { "code": "MAP_DUPLICATE_TARGET", "issues": [ { "code": "MAP_DUPLICATE_TARGET", "severity": "danger", "targetPath": "invoiceNumber", "sourceField": "header.tranid" } ] } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/mappings/{mappingId}/simulate": { "post": { "operationId": "postTenantMappingsByMappingIdSimulate", "summary": "Simulate a mapping against a sample record", "description": "Applies the given connections to a stored sample (`sampleId`, or the first sample) and runs the result through the same validator that gates submission, returning the mapped values, the issues (genuine PINT rule failures as `danger`) and a 0–100 readiness score. The supplier comes from the tenant's default company; when its profile is incomplete a placeholder supplier is used and `MAP_SUPPLIER_PLACEHOLDER` is added as a warning. Nothing is saved. Open to any tenant user.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Mappings" ], "parameters": [ { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 80 }, "source": { "type": "string", "maxLength": 300 }, "target": { "type": "string", "maxLength": 300 }, "transform": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "direct", "formula", "lookup", "conditional" ] }, "expression": { "type": "string", "maxLength": 500 }, "pairs": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "maxLength": 200 }, "to": { "type": "string", "maxLength": 200 } }, "required": [ "from", "to" ] }, "maxItems": 100 }, "field": { "type": "string", "maxLength": 200 }, "value": { "type": "string", "maxLength": 200 }, "then": { "type": "string", "maxLength": 200 }, "else": { "type": "string", "maxLength": 200 } }, "required": [ "type" ], "additionalProperties": false } }, "required": [ "id", "source", "target" ], "additionalProperties": false }, "maxItems": 200 }, "sampleId": { "type": "string", "maxLength": 80 } }, "required": [ "connections" ], "additionalProperties": false }, "example": { "connections": [ { "id": "c1", "source": "header.tranid", "target": "invoiceNumber", "transform": { "type": "direct" } }, { "id": "c2", "source": "header.trandate", "target": "issueDate", "transform": { "type": "direct" } }, { "id": "c3", "source": "item[].taxcode", "target": "lines[].taxCategory", "transform": { "type": "lookup", "pairs": [ { "from": "VAT_AE:S", "to": "S" }, { "from": "VAT_AE:Z", "to": "Z" } ] } } ], "sampleId": "sample_1729502043000_0b9e…" } } } }, "responses": { "200": { "description": "Simulation result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "object", "properties": { "targetPath": { "type": "string" }, "value": { "type": "string" }, "sourceField": { "type": "string" }, "transform": { "type": "string" } } } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "targetPath": { "type": "string" }, "sourceField": { "type": "null" }, "code": { "type": "string" }, "severity": { "type": "string" }, "message": { "type": "string" } } } }, "score": { "type": "integer" } } }, "example": { "values": [ { "targetPath": "invoiceNumber", "value": "INV-1042", "sourceField": "header.tranid", "transform": "direct" }, { "targetPath": "taxTotal.taxAmount", "value": "22.5", "sourceField": null, "transform": "direct" } ], "issues": [ { "targetPath": "customer.taxId", "sourceField": null, "code": "PINT_BR_AE_…", "severity": "danger", "message": "Buyer VAT identifier is required" } ], "score": 85 } } } }, "400": { "description": "Rejected by a mapping rule. The body carries only `error.code` (no `message`), plus `unmapped` or `issues` where relevant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" } } } } }, "example": { "error": { "code": "NO_SAMPLES" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/mappings/{mappingId}/activate": { "post": { "operationId": "postTenantMappingsByMappingIdActivate", "summary": "Activate a mapping draft", "description": "Makes the given Draft version the Active one (the previous Active becomes Archived); from then on it is applied to `inputType: \"mapped\"` submissions. Every required PINT target must be mapped, otherwise 400 `REQUIRED_UNMAPPED` with the `unmapped` list. `approver` is free text from the request and is appended to the note and audit row. `tenant_admin` only.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Mappings" ], "parameters": [ { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "exclusiveMinimum": 0 }, "approver": { "type": "string", "maxLength": 120 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "version", "approver", "note" ], "additionalProperties": false }, "example": { "version": 2, "approver": "Finance lead", "note": "Adds VAT lookup" } } } }, "responses": { "200": { "description": "All versions after activation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "status": { "type": "string" }, "author": { "type": "string" }, "date": { "type": "string" }, "note": { "type": "string" }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" }, "transform": { "type": "object", "properties": { "type": { "type": "string" } } } } } } } } }, "activatedVersion": { "type": "integer" } } }, "example": { "versions": [ { "version": 1, "status": "Archived", "author": "o***@example.com", "date": "2026-10-01T08:00:00.000Z", "note": "Go-live (approved by Finance lead)", "connections": [ { "id": "c1", "source": "header.tranid", "target": "invoiceNumber", "transform": { "type": "direct" } }, { "id": "c2", "source": "header.trandate", "target": "issueDate", "transform": { "type": "direct" } }, { "id": "c3", "source": "item[].taxcode", "target": "lines[].taxCategory", "transform": { "type": "lookup", "pairs": [ { "from": "VAT_AE:S", "to": "S" }, { "from": "VAT_AE:Z", "to": "Z" } ] } } ] }, { "version": 2, "status": "Active", "author": "o***@example.com", "date": "2026-10-21T09:14:03.000Z", "note": "Adds VAT lookup (approved by Finance lead)", "connections": [ { "id": "c1", "source": "header.tranid", "target": "invoiceNumber", "transform": { "type": "direct" } }, { "id": "c2", "source": "header.trandate", "target": "issueDate", "transform": { "type": "direct" } }, { "id": "c3", "source": "item[].taxcode", "target": "lines[].taxCategory", "transform": { "type": "lookup", "pairs": [ { "from": "VAT_AE:S", "to": "S" }, { "from": "VAT_AE:Z", "to": "Z" } ] } } ] } ], "activatedVersion": 2 } } } }, "400": { "description": "Rejected by a mapping rule. The body carries only `error.code` (no `message`), plus `unmapped` or `issues` where relevant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "unmapped": { "type": "array", "items": { "type": "string" } } } } } }, "example": { "error": { "code": "REQUIRED_UNMAPPED", "unmapped": [ "customer.taxId" ] } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/mappings/{mappingId}/rollback": { "post": { "operationId": "postTenantMappingsByMappingIdRollback", "summary": "Roll a mapping back to an archived version", "description": "Copies the connections of an Archived version into a new version that becomes Active (the current Active is archived). `toVersion` must be Archived (`NOT_ARCHIVED` otherwise). `approver` (free text) becomes the new version's author. `tenant_admin` only; audited.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Mappings" ], "parameters": [ { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "toVersion": { "type": "integer", "exclusiveMinimum": 0 }, "approver": { "type": "string", "maxLength": 120 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "toVersion", "approver", "note" ], "additionalProperties": false }, "example": { "toVersion": 1, "approver": "Finance lead", "note": "VAT lookup rejected by receiver" } } } }, "responses": { "200": { "description": "All versions after the rollback.", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "status": { "type": "string" }, "author": { "type": "string" }, "date": { "type": "string" }, "note": { "type": "string" }, "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" }, "transform": { "type": "object", "properties": { "type": { "type": "string" } } } } } } } } }, "activatedVersion": { "type": "integer" } } }, "example": { "versions": [ { "version": 1, "status": "Archived", "author": "o***@example.com", "date": "2026-10-01T08:00:00.000Z", "note": "Go-live (approved by Finance lead)", "connections": [ { "id": "c1", "source": "header.tranid", "target": "invoiceNumber", "transform": { "type": "direct" } }, { "id": "c2", "source": "header.trandate", "target": "issueDate", "transform": { "type": "direct" } }, { "id": "c3", "source": "item[].taxcode", "target": "lines[].taxCategory", "transform": { "type": "lookup", "pairs": [ { "from": "VAT_AE:S", "to": "S" }, { "from": "VAT_AE:Z", "to": "Z" } ] } } ] }, { "version": 2, "status": "Archived", "author": "o***@example.com", "date": "2026-10-21T09:14:03.000Z", "note": "Draft in progress.", "connections": [ { "id": "c1", "source": "header.tranid", "target": "invoiceNumber", "transform": { "type": "direct" } }, { "id": "c2", "source": "header.trandate", "target": "issueDate", "transform": { "type": "direct" } }, { "id": "c3", "source": "item[].taxcode", "target": "lines[].taxCategory", "transform": { "type": "lookup", "pairs": [ { "from": "VAT_AE:S", "to": "S" }, { "from": "VAT_AE:Z", "to": "Z" } ] } } ] }, { "version": 3, "status": "Active", "author": "Finance lead", "date": "2026-10-21T09:14:41.000Z", "note": "Rolled back to v1 — VAT lookup rejected by receiver (approved by Finance lead)", "connections": [ { "id": "c1", "source": "header.tranid", "target": "invoiceNumber", "transform": { "type": "direct" } }, { "id": "c2", "source": "header.trandate", "target": "issueDate", "transform": { "type": "direct" } }, { "id": "c3", "source": "item[].taxcode", "target": "lines[].taxCategory", "transform": { "type": "lookup", "pairs": [ { "from": "VAT_AE:S", "to": "S" }, { "from": "VAT_AE:Z", "to": "Z" } ] } } ] } ], "activatedVersion": 3 } } } }, "400": { "description": "Rejected by a mapping rule. The body carries only `error.code` (no `message`), plus `unmapped` or `issues` where relevant.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" } } } } }, "example": { "error": { "code": "NOT_ARCHIVED" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/mappings/{mappingId}/diff": { "get": { "operationId": "getTenantMappingsByMappingIdDiff", "summary": "Compare two mapping versions", "description": "Diffs the connections of versions `from` and `to` by target field: connections only in `to` are `added`, only in `from` are `removed`, and those whose source or transform differ are `changed`. Both query parameters are required integers.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Mappings" ], "parameters": [ { "name": "mappingId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "description": "Base version number.", "schema": { "type": "integer" } }, { "name": "to", "in": "query", "required": true, "description": "Compared version number.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Connection diff.", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" }, "transform": { "type": "object", "properties": { "type": { "type": "string" }, "pairs": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } } } } } } } }, "removed": { "type": "array", "items": {} }, "changed": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string" }, "from": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" } } }, "to": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" }, "transform": { "type": "object", "properties": { "type": { "type": "string" } } } } } } } } } }, "example": { "added": [ { "id": "c3", "source": "item[].taxcode", "target": "lines[].taxCategory", "transform": { "type": "lookup", "pairs": [ { "from": "VAT_AE:S", "to": "S" }, { "from": "VAT_AE:Z", "to": "Z" } ] } } ], "removed": [], "changed": [ { "target": "issueDate", "from": { "id": "c2", "source": "header.createddate", "target": "issueDate" }, "to": { "id": "c2", "source": "header.trandate", "target": "issueDate", "transform": { "type": "direct" } } } ] } } } }, "400": { "description": "`from` or `to` is missing or not an integer (bare code, no `message`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" } } } } }, "example": { "error": { "code": "BAD_VERSIONS" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/insights-schedules": { "get": { "operationId": "getTenantInsightsSchedules", "summary": "List scheduled report emails", "description": "The schedules (this tenant) with their next and last run and the last 10 runs, plus `allowedRecipients`: the addresses that may be chosen (the tenant's contact (shared onboarding) email and its active portal users (tenant admins and users)) and the limits (20 schedules, 10 recipients each).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "responses": { "200": { "description": "Schedules and allowed recipients.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "scheduleId": { "type": "string" }, "scope": { "type": "string" }, "report": { "type": "string" }, "frequency": { "type": "string" }, "weekday": { "type": "integer" }, "hour": { "type": "integer" }, "filters": { "type": "object", "properties": { "environment": { "type": "string" }, "direction": { "type": "string" } } }, "recipients": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "nextRunAt": { "type": "string" }, "lastStatus": { "type": "string" } } } }, "allowedRecipients": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "label": { "type": "string" } } } }, "limits": { "type": "object", "properties": { "schedules": { "type": "integer" }, "recipients": { "type": "integer" } } } } }, "example": { "items": [ { "scheduleId": "sch_3f2a9c1d7b4e6a80", "scope": "tenant", "report": "volume", "frequency": "weekly", "weekday": 1, "hour": 8, "filters": { "environment": "production", "direction": "all" }, "recipients": [ "finance@acme.ae" ], "enabled": true, "nextRunAt": "2026-11-02T04:00:00.000Z", "lastStatus": "sent" } ], "allowedRecipients": [ { "email": "finance@acme.ae", "label": "Finance (user)" } ], "limits": { "schedules": 20, "recipients": 10 } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "post": { "operationId": "postTenantInsightsSchedules", "summary": "Create a scheduled report email", "description": "Sends one report by email on a schedule: `report` = `volume`, `vat`, `delivery`, `partners`; `frequency` = `weekly` (`weekday` 1–7, ISO, Monday = 1) or `monthly` (`dayOfMonth` 1–28); `hour` 0–23 Dubai time (default 08:00). Each run covers the last full period (previous ISO week or previous calendar month, Dubai time) compared with the period before, and the email has a KPI summary, a link to the report and the Excel export attached. `recipients` (1–10) must be the tenant's contact (shared onboarding) email and its active portal users (tenant admins and users); they are checked again at every send, so a removed user stops receiving reports. Optional `filters`: `environment`, `direction`. Write access: tenant_admin or super_admin (403 otherwise). Audit-logged.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "201": { "description": "The schedule.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduleId": { "type": "string" }, "scope": { "type": "string" }, "report": { "type": "string" }, "frequency": { "type": "string" }, "weekday": { "type": "integer" }, "hour": { "type": "integer" }, "filters": { "type": "object", "properties": { "environment": { "type": "string" }, "direction": { "type": "string" } } }, "recipients": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "nextRunAt": { "type": "string" }, "lastStatus": { "type": "string" } } }, "example": { "scheduleId": "sch_3f2a9c1d7b4e6a80", "scope": "tenant", "report": "volume", "frequency": "weekly", "weekday": 1, "hour": 8, "filters": { "environment": "production", "direction": "all" }, "recipients": [ "finance@acme.ae" ], "enabled": true, "nextRunAt": "2026-11-02T04:00:00.000Z", "lastStatus": "sent" } } } }, "400": { "description": "Invalid body or `RECIPIENT_NOT_ALLOWED` (rejected addresses in `details.rejected`)." }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "description": "Not allowed to change schedules." }, "409": { "description": "`SCHEDULE_LIMIT` (20)." }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/insights-schedules/{scheduleId}": { "delete": { "operationId": "deleteTenantInsightsSchedulesByScheduleId", "summary": "Delete a scheduled report email", "description": "Removes the schedule. Audit-logged.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "example": { "deleted": true } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "description": "No such schedule for this caller." }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "patch": { "operationId": "patchTenantInsightsSchedulesByScheduleId", "summary": "Change a scheduled report email", "description": "Any of the create fields; the next run is recalculated (none while `enabled` is false). Recipients are re-checked. Only the caller's own schedules (this tenant). Audit-logged.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "The updated schedule." }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "description": "No such schedule for this caller." }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/insights-schedules/{scheduleId}/send-now": { "post": { "operationId": "postTenantInsightsSchedulesByScheduleIdSendNow", "summary": "Send a scheduled report now", "description": "Builds and emails the report for the last full period immediately, without moving the schedule. Once a minute per schedule. Returns the run: `status` `sent`, `skipped` (no recipient is still allowed) or `failed` (with `error`).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "The run.", "content": { "application/json": { "schema": { "type": "object", "properties": { "at": { "type": "string" }, "trigger": { "type": "string" }, "status": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "recipients": { "type": "integer" }, "error": { "type": "null" } } }, "example": { "at": "2026-10-25T18:00:00.000Z", "trigger": "manual", "status": "sent", "from": "2026-10-19", "to": "2026-10-25", "recipients": 2, "error": null } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "429": { "description": "`TOO_SOON`: sent less than a minute ago." }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/insights/{report}": { "get": { "operationId": "getTenantInsightsByReport", "summary": "Get an Insights report", "description": "Exact aggregation over every matching platform transaction (no row cap, unlike `/api/tenant/reports/*`). `report` is `volume` (Volume & trends: business documents and Tax Data Documents per period, sent vs received, delivery rate, by document kind, daily calendar, weekday × hour heatmap) or `vat` (VAT & invoice value: sales = sent documents, purchases = received, credit notes netted, output/input VAT, VAT by category, largest documents, coverage; AED in the KPIs and charts, other currencies listed separately, never converted), `delivery` (Delivery, MLS & failures: sent business documents, delivery rate, time to delivery median/95th percentile and distribution, failures by stage and reason with the latest affected documents, and the receiver's Message Level Status from the AP — accepted/acknowledged/rejected/awaiting — with response time against the 10-minute SLA and the latest rejections) or `partners` (Partners & FTA reporting: top counterparties by documents with AED value net of credit notes, delivery rate, share and last activity, names from the tenant's customer list, partners first seen in the period; Tax Data Documents sent to the FTA with the FTA's answer from the AP MLS — accepted/rejected/awaiting/not delivered — response times and the latest rejections). AP figures come from linking the period's platform rows to AP rows (live + archive); at most the 5,000 most recent rows are linked and the response says when the AP figures are a sample. Period: `from`/`to` are Dubai calendar days, both inclusive (default: the last 30 days, at most 731). `granularity` = `auto` (day up to 45 days, week up to 200, then month), `day`, `week` (ISO, from Monday) or `month`. With `compare` (default `true`) each KPI carries the previous period of the same length and the change in %. Filters: `environment` (Peppol network), `direction`, `subsidiaryId`. tenant_user callers only see their allowed companies / Peppol identities. Results are cached for 30 s. Unknown query parameters are rejected.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "name": "report", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "granularity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "auto", "day", "week", "month" ] } }, { "name": "environment", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "test", "production" ] } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "inbound", "outbound" ] } }, { "name": "subsidiaryId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "The report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "report": { "type": "string" }, "title": { "type": "string" }, "period": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "granularity": { "type": "string" }, "timezone": { "type": "string" } } }, "previous": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "generatedAt": { "type": "string" }, "kpis": { "type": "object", "properties": { "documents": { "type": "object", "properties": { "current": { "type": "integer" }, "previous": { "type": "integer" }, "change": { "type": "number" } } }, "deliveryRate": { "type": "object", "properties": { "current": { "type": "number" }, "previous": { "type": "number" }, "change": { "type": "number" } } } } }, "series": { "type": "array", "items": { "type": "object", "properties": { "bucket": { "type": "string" }, "sent": { "type": "integer" }, "received": { "type": "integer" }, "invoice": { "type": "integer" }, "credit_note": { "type": "integer" }, "tdd": { "type": "integer" } } } } } }, "example": { "report": "volume", "title": "Volume & trends", "period": { "from": "2026-09-26", "to": "2026-10-25", "granularity": "day", "timezone": "Asia/Dubai" }, "previous": { "from": "2026-08-27", "to": "2026-09-25" }, "generatedAt": "2026-10-25T18:00:00.000Z", "kpis": { "documents": { "current": 412, "previous": 380, "change": 8.4 }, "deliveryRate": { "current": 97.6, "previous": 96.1, "change": 1.5 } }, "series": [ { "bucket": "2026-10-20", "sent": 18, "received": 4, "invoice": 19, "credit_note": 3, "tdd": 21 } ] } } } }, "400": { "description": "Unknown report or parameter, `from` after `to`, or a period over 731 days." }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/insights/{report}/export": { "get": { "operationId": "getTenantInsightsByReportExport", "summary": "Export an Insights report", "description": "The same report and filters as `GET /api/tenant/insights/{report}`, as a file. `format=xlsx` (default): an Excel workbook with one sheet per table (typed numbers, dates and AED amounts, frozen header). `format=csv`: the main table only, UTF-8 with a byte-order mark, formula-like cells neutralised. Sent as an attachment named `azdan-{report}-{from}_{to}.{ext}`.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "name": "report", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "granularity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "auto", "day", "week", "month" ] } }, { "name": "environment", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "test", "production" ] } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "inbound", "outbound" ] } }, { "name": "subsidiaryId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "compare", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "csv", "xlsx" ] } } ], "responses": { "200": { "description": "The file (`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` or `text/csv`)." }, "400": { "description": "Unknown report, format or parameter." }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/analytics": { "get": { "operationId": "getTenantAnalytics", "summary": "Get console analytics for a date range", "description": "One aggregation over the tenant's platform transactions (all rows, including tax-data and MLS transport rows) feeding the console charts: daily series (every day in range, zero-filled), a documentType → direction → status flow, VAT by category with coverage, failure stages and the top 8 failure reasons, and totals. Default range: the 91 days ending today; `to` is inclusive. Amounts are summed as stored (`amount`, `taxAmount`). tenant_user callers only see their allowed companies / Peppol identities. Unknown query parameters are rejected (strict schema).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Dashboard & compliance" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T.*)?$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(T.*)?$" } }, { "name": "subsidiaryId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 80 } }, { "name": "environment", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "test", "production" ] } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "inbound", "outbound" ] } } ], "responses": { "200": { "description": "The console datasets.", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "totals": { "type": "object", "properties": { "documents": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" }, "value": { "type": "number" }, "vat": { "type": "number" } } }, "timeseries": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "outbound": { "type": "integer" }, "inbound": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" }, "value": { "type": "number" }, "vat": { "type": "number" } } } }, "flow": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" } } } }, "links": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" }, "value": { "type": "integer" } } } } } }, "vat": { "type": "object", "properties": { "byCategory": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "taxableAmount": { "type": "integer" }, "taxAmount": { "type": "number" } } } }, "coverage": { "type": "object", "properties": { "total": { "type": "integer" }, "withVat": { "type": "integer" } } } } }, "exceptions": { "type": "object", "properties": { "byStage": { "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string" }, "count": { "type": "integer" } } } }, "topReasons": { "type": "array", "items": { "type": "object", "properties": { "reason": { "type": "string" }, "count": { "type": "integer" } } } } } } } }, "example": { "range": { "from": "2026-09-24", "to": "2026-10-24" }, "totals": { "documents": 412, "delivered": 398, "failed": 6, "pending": 8, "value": 1824500.75, "vat": 86880.04 }, "timeseries": [ { "date": "2026-10-20", "outbound": 18, "inbound": 4, "delivered": 21, "failed": 1, "pending": 0, "value": 61250.5, "vat": 2916.69 } ], "flow": { "nodes": [ { "name": "invoice" }, { "name": "outbound" }, { "name": "delivered" } ], "links": [ { "source": "invoice", "target": "outbound", "value": 350 }, { "source": "outbound", "target": "delivered", "value": 342 } ] }, "vat": { "byCategory": [ { "category": "S", "taxableAmount": 1737620, "taxAmount": 86880.04 } ], "coverage": { "total": 412, "withVat": 389 } }, "exceptions": { "byStage": [ { "stage": "ap_core_response", "count": 4 } ], "topReasons": [ { "reason": "Receiver endpoint not found in SMP", "count": 3 } ] } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/dashboard": { "get": { "operationId": "getTenantDashboard", "summary": "Get the tenant dashboard summary", "description": "Status and direction counts over all of the tenant's platform transactions, the 24-hour success rate (share of rows created in the last 24 h whose status falls in the SUCCESS bucket; 1 when there were none), the 10 most recent transactions (projected ledger rows, without AP enrichment or `statusDetail`) and the tenant's webhooks (secrets removed). `queued` counts `queued` + `sending`. Not narrowed by a `tenant_user`'s company scope.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Dashboard & compliance" ], "responses": { "200": { "description": "The dashboard summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenantId": { "type": "string" }, "counts": { "type": "object", "properties": { "total": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "queued": { "type": "integer" }, "inbound": { "type": "integer" }, "outbound": { "type": "integer" } } }, "successRate24h": { "type": "number" }, "recentTransactions": { "type": "array", "items": { "type": "object", "properties": { "transactionId": { "type": "string" }, "tenantId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "direction": { "type": "string" }, "status": { "type": "string" }, "documentType": { "type": "string" }, "documentTypeId": { "type": "string" }, "processId": { "type": "string" }, "environment": { "type": "string" }, "c1CountryCode": { "type": "string" }, "sender": { "type": "object", "properties": { "participantId": { "type": "string" }, "name": { "type": "string" } } }, "receiver": { "type": "object", "properties": { "participantId": { "type": "string" } } }, "correlationId": { "type": "string" }, "apCoreMessageId": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "sizeBytes": { "type": "integer" }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "taxAmount": { "type": "integer" }, "taxExclusiveAmount": { "type": "integer" }, "taxBreakdown": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "percent": { "type": "string" }, "taxableAmount": { "type": "integer" }, "taxAmount": { "type": "integer" } } } }, "document": { "type": "object", "properties": { "number": { "type": "string" }, "issueDate": { "type": "string" }, "dueDate": { "type": "string" }, "currency": { "type": "string" }, "typeCode": { "type": "string" }, "supplierName": { "type": "string" }, "customerName": { "type": "string" }, "netAmount": { "type": "integer" }, "taxAmount": { "type": "integer" }, "payableAmount": { "type": "integer" } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "deliveredAt": { "type": "string" }, "attempts": { "type": "integer" }, "lastAttemptAt": { "type": "string" } } } }, "webhooks": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "webhookId": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "subsidiaryId": { "type": "null" }, "payloadVersion": { "type": "string" }, "status": { "type": "string" }, "signingSecretRotatedAt": { "type": "null" }, "previousSecretValidUntil": { "type": "null" }, "health": { "type": "object", "properties": { "consecutiveFailures": { "type": "integer" }, "successRate24h": { "type": "integer" }, "lastDeliveryAt": { "type": "string" }, "lastSuccessAt": { "type": "string" } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "hasSigningSecret": { "type": "boolean" }, "auth": { "type": "object", "properties": { "type": { "type": "string" }, "configured": { "type": "boolean" }, "display": { "type": "string" } } } } } } } }, "example": { "tenantId": "tnt_7Q2X…", "counts": { "total": 1287, "delivered": 1240, "failed": 21, "queued": 6, "inbound": 312, "outbound": 975 }, "successRate24h": 0.97, "recentTransactions": [ { "transactionId": "txn_1789562400000_9f3a…", "tenantId": "tnt_7Q2X…", "subsidiaryId": "sub_1789…_a1b2", "direction": "outbound", "status": "delivered", "documentType": "invoice", "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "environment": "production", "c1CountryCode": "AE", "sender": { "participantId": "0235:1004****59", "name": "Sample Trading LLC" }, "receiver": { "participantId": "0235:1002****03" }, "correlationId": "cor_1789562400000_4d5e…", "apCoreMessageId": "f0debc61-…@peppol.azdanapps.com", "sbdhInstanceId": "6c1d2e3f-…", "sizeBytes": 18432, "amount": 1050, "currency": "AED", "taxAmount": 50, "taxExclusiveAmount": 1000, "taxBreakdown": [ { "category": "S", "percent": "5", "taxableAmount": 1000, "taxAmount": 50 } ], "document": { "number": "INV-2026-000123", "issueDate": "2026-10-20", "dueDate": "2026-11-19", "currency": "AED", "typeCode": "380", "supplierName": "Sample Trading LLC", "customerName": "Sample Buyer FZ-LLC", "netAmount": 1000, "taxAmount": 50, "payableAmount": 1050 }, "createdAt": "2026-10-20T09:00:00.000Z", "updatedAt": "2026-10-20T09:02:41.000Z", "deliveredAt": "2026-10-20T09:00:04.000Z", "attempts": 1, "lastAttemptAt": "2026-10-20T09:00:02.000Z" } ], "webhooks": [ { "_id": "671f3a…", "webhookId": "whk_1789562400000_k3j9a1", "tenantId": "tnt_7Q2X…", "name": "ERP production", "url": "https://erp.example.com/hooks/azdan", "events": [ "document.delivered", "document.failed", "mls.rejected" ], "subsidiaryId": null, "payloadVersion": "2", "status": "active", "signingSecretRotatedAt": null, "previousSecretValidUntil": null, "health": { "consecutiveFailures": 0, "successRate24h": 1, "lastDeliveryAt": "2026-10-20T09:02:45.000Z", "lastSuccessAt": "2026-10-20T09:02:45.000Z" }, "createdAt": "2026-09-02T10:00:00.000Z", "updatedAt": "2026-10-01T11:30:00.000Z", "hasSigningSecret": true, "auth": { "type": "bearer", "configured": true, "display": "Bearer ••••••••••••" } } ] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/transactions": { "get": { "operationId": "getTenantTransactions", "summary": "List transactions", "description": "Paged ledger of the tenant's platform transactions, newest first, each enriched from AP Core (AP status, MLS, link state) and carrying `documentKind`, `statusDetail` and the status `bucket`. Filters: `direction`, `status`, `bucket`, `subsidiaryId`, `peppolParticipantId`, `environment`, `from` / `to` (created time) and `q` (transaction id, document type, correlation id, participant ids, document number, customer name). `view=documents` leaves out MLS and tax-data transport rows. On page 1, when no `subsidiaryId`, `environment`, `q` or `peppolParticipantId` filter is set, up to 50 AP-only rows (traffic that never went through the Platform API, `source: \"ap-core\"`, `linkState: \"ap_only\"`) are merged in; `page.total` counts platform rows only. In list rows outbound `statusDetail.reporting` is `unknown` (the TDD is only resolved in the detail). tenant_user callers only see rows of their allowed companies / Peppol identities; with no allow-list the list is empty.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Transactions" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 } }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inbound", "outbound" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "bucket", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "SUCCESS", "FAILED", "PENDING", "OTHER" ] } }, { "name": "subsidiaryId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "peppolParticipantId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "environment", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "test", "production" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "documents" ] } }, { "name": "documentKind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "invoice", "credit_note", "self_billing_invoice", "self_billing_credit_note", "tdd", "mls", "other" ] } }, { "name": "counterparty", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 } }, { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 80 } }, { "name": "amountMin", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 } }, { "name": "amountMax", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 } } ], "responses": { "200": { "description": "One page of transactions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "transactionId": { "type": "string" }, "tenantId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "direction": { "type": "string" }, "status": { "type": "string" }, "documentType": { "type": "string" }, "documentTypeId": { "type": "string" }, "processId": { "type": "string" }, "environment": { "type": "string" }, "c1CountryCode": { "type": "string" }, "sender": { "type": "object", "properties": { "participantId": { "type": "string" }, "name": { "type": "string" } } }, "receiver": { "type": "object", "properties": { "participantId": { "type": "string" } } }, "correlationId": { "type": "string" }, "apCoreMessageId": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "sizeBytes": { "type": "integer" }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "taxAmount": { "type": "integer" }, "taxExclusiveAmount": { "type": "integer" }, "taxBreakdown": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "percent": { "type": "string" }, "taxableAmount": { "type": "integer" }, "taxAmount": { "type": "integer" } } } }, "document": { "type": "object", "properties": { "number": { "type": "string" }, "issueDate": { "type": "string" }, "dueDate": { "type": "string" }, "currency": { "type": "string" }, "typeCode": { "type": "string" }, "supplierName": { "type": "string" }, "customerName": { "type": "string" }, "netAmount": { "type": "integer" }, "taxAmount": { "type": "integer" }, "payableAmount": { "type": "integer" } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "deliveredAt": { "type": "string" }, "attempts": { "type": "integer" }, "lastAttemptAt": { "type": "string" }, "source": { "type": "string" }, "apStatus": { "type": "string" }, "apTransactionId": { "type": "string" }, "apMessageId": { "type": "string" }, "mlsStatus": { "type": "string" }, "mlsType": { "type": "string" }, "mlsResponseCode": { "type": "null" }, "tddStatus": { "type": "null" }, "isTdd": { "type": "boolean" }, "linkState": { "type": "string" }, "documentKind": { "type": "string" }, "statusDetail": { "type": "object", "properties": { "documentKind": { "type": "string" }, "overall": { "type": "string" }, "processing": { "type": "object", "properties": { "platformStatus": { "type": "string" }, "apStatus": { "type": "string" }, "source": { "type": "string" }, "createdAt": { "type": "string" }, "failureStage": { "type": "null" } } }, "validation": { "type": "object", "properties": { "state": { "type": "string" }, "engine": { "type": "string" }, "at": { "type": "string" }, "warnings": { "type": "integer" }, "error": { "type": "null" } } }, "delivery": { "type": "object", "properties": { "state": { "type": "string" }, "apStatus": { "type": "string" }, "platformStatus": { "type": "string" }, "attempts": { "type": "integer" }, "lastAttemptAt": { "type": "string" }, "completedAt": { "type": "string" }, "failedAt": { "type": "null" }, "errorCode": { "type": "null" }, "error": { "type": "null" } } }, "mls": { "type": "object", "properties": { "role": { "type": "string" }, "state": { "type": "string" }, "code": { "type": "string" }, "raw": { "type": "string" }, "at": { "type": "string" }, "mlsId": { "type": "string" }, "errorCode": { "type": "null" }, "errorMessage": { "type": "null" }, "policy": { "type": "string" } } }, "reporting": { "type": "object", "properties": { "state": { "type": "string" } } } } }, "bucket": { "type": "string" } } } }, "page": { "type": "object", "properties": { "number": { "type": "integer" }, "size": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } }, "example": { "items": [ { "transactionId": "txn_1789562400000_9f3a…", "tenantId": "tnt_7Q2X…", "subsidiaryId": "sub_1789…_a1b2", "direction": "outbound", "status": "delivered", "documentType": "invoice", "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "environment": "production", "c1CountryCode": "AE", "sender": { "participantId": "0235:1004****59", "name": "Sample Trading LLC" }, "receiver": { "participantId": "0235:1002****03" }, "correlationId": "cor_1789562400000_4d5e…", "apCoreMessageId": "f0debc61-…@peppol.azdanapps.com", "sbdhInstanceId": "6c1d2e3f-…", "sizeBytes": 18432, "amount": 1050, "currency": "AED", "taxAmount": 50, "taxExclusiveAmount": 1000, "taxBreakdown": [ { "category": "S", "percent": "5", "taxableAmount": 1000, "taxAmount": 50 } ], "document": { "number": "INV-2026-000123", "issueDate": "2026-10-20", "dueDate": "2026-11-19", "currency": "AED", "typeCode": "380", "supplierName": "Sample Trading LLC", "customerName": "Sample Buyer FZ-LLC", "netAmount": 1000, "taxAmount": 50, "payableAmount": 1050 }, "createdAt": "2026-10-20T09:00:00.000Z", "updatedAt": "2026-10-20T09:02:41.000Z", "deliveredAt": "2026-10-20T09:00:04.000Z", "attempts": 1, "lastAttemptAt": "2026-10-20T09:00:02.000Z", "source": "platform", "apStatus": "sent", "apTransactionId": "a3c5e7f9-…", "apMessageId": "f0debc61-…@peppol.azdanapps.com", "mlsStatus": "received_ap", "mlsType": "ALWAYS_SEND", "mlsResponseCode": null, "tddStatus": null, "isTdd": false, "linkState": "linked", "documentKind": "invoice", "statusDetail": { "documentKind": "invoice", "overall": "accepted", "processing": { "platformStatus": "delivered", "apStatus": "sent", "source": "platform+ap", "createdAt": "2026-10-20T09:00:00.000Z", "failureStage": null }, "validation": { "state": "passed", "engine": "internal", "at": "2026-10-20T08:59:59.000Z", "warnings": 0, "error": null }, "delivery": { "state": "delivered", "apStatus": "sent", "platformStatus": "delivered", "attempts": 1, "lastAttemptAt": "2026-10-20T09:00:02.000Z", "completedAt": "2026-10-20T09:00:04.000Z", "failedAt": null, "errorCode": null, "error": null }, "mls": { "role": "received", "state": "accepted", "code": "AP", "raw": "received_ap", "at": "2026-10-20T09:02:40.000Z", "mlsId": "mls-3e1f…", "errorCode": null, "errorMessage": null, "policy": "ALWAYS_SEND" }, "reporting": { "state": "unknown" } }, "bucket": "SUCCESS" }, { "transactionId": "e41d9b2c-…", "source": "ap-core", "direction": "inbound", "status": "forwarded", "apStatus": "forwarded", "apTransactionId": "e41d9b2c-…", "apMessageId": "77aa01bc-…@ap.example.com", "sender": { "participantId": "0235:1003****11", "name": null }, "receiver": { "participantId": "0235:1004****59", "name": null }, "documentType": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "sbdhInstanceId": "1b2c3d4e-…", "mlsStatus": null, "mlsType": "ALWAYS_SEND", "mlsResponseCode": "AP", "tddStatus": "sent", "isTdd": false, "correlationId": null, "documentKind": "invoice", "statusDetail": { "documentKind": "invoice", "overall": "delivered", "processing": { "platformStatus": null, "apStatus": "forwarded", "source": "ap", "createdAt": "2026-10-19T14:20:00.000Z", "failureStage": null }, "validation": { "state": "passed", "engine": "ap_core", "at": "2026-10-19T14:20:00.000Z", "warnings": 0, "error": null }, "delivery": { "state": "delivered", "apStatus": "forwarded", "platformStatus": null, "attempts": 1, "lastAttemptAt": null, "completedAt": "2026-10-19T14:20:03.000Z", "failedAt": null, "errorCode": null, "error": null }, "mls": { "role": "sent", "state": "accepted", "code": "AP", "raw": "AP", "at": null, "mlsId": null, "errorCode": null, "errorMessage": null, "policy": "ALWAYS_SEND" }, "reporting": { "state": "reported", "raw": "sent", "at": "2026-10-19T14:20:05.000Z", "error": null, "ftaResponse": null } }, "createdAt": "2026-10-19T14:20:00.000Z", "completedAt": "2026-10-19T14:20:03.000Z", "sizeBytes": 15220, "tenantId": "tnt_7Q2X…", "linkState": "ap_only" } ], "page": { "number": 1, "size": 25, "total": 1287, "totalPages": 52 } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/transactions/{transactionId}": { "get": { "operationId": "getTenantTransactionsByTransactionId", "summary": "Get a transaction with its full status story", "description": "Everything known about one transaction: the projected ledger row (`transaction`), its files (`files`, including the TDD / MLS files generated for it), status events, the linked AP Core row (`ap`), payload `availability`, the unified `documents` download links, and the derived status: `statusDetail` (separate `overall`, `processing`, `validation`, `delivery`, `mls`, `reporting` dimensions plus `documentKind`), the delivery `journey` timeline, `apLog` and the resolved `tdd`. Top-level `status` is the derived portal status (`delivered`, `failed`, `sending`, `quarantined`, `validated`), not the ledger status. An id that is not a `txn_…` platform id is also looked up as an AP Core transaction id (AP-only rows, `source: \"ap-core\"`). Out of a `tenant_user`'s scope answers 404.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Transactions" ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The transaction detail. Example: an outbound invoice accepted by the receiver (MLS AP) whose TDD the FTA accepted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction": { "type": "object", "properties": { "transactionId": { "type": "string" }, "tenantId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "direction": { "type": "string" }, "status": { "type": "string" }, "documentType": { "type": "string" }, "documentTypeId": { "type": "string" }, "processId": { "type": "string" }, "environment": { "type": "string" }, "c1CountryCode": { "type": "string" }, "sender": { "type": "object", "properties": { "participantId": { "type": "string" }, "name": { "type": "string" } } }, "receiver": { "type": "object", "properties": { "participantId": { "type": "string" } } }, "correlationId": { "type": "string" }, "apCoreMessageId": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "sizeBytes": { "type": "integer" }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "taxAmount": { "type": "integer" }, "taxExclusiveAmount": { "type": "integer" }, "taxBreakdown": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "percent": { "type": "string" }, "taxableAmount": { "type": "integer" }, "taxAmount": { "type": "integer" } } } }, "document": { "type": "object", "properties": { "number": { "type": "string" }, "issueDate": { "type": "string" }, "dueDate": { "type": "string" }, "currency": { "type": "string" }, "typeCode": { "type": "string" }, "supplierName": { "type": "string" }, "customerName": { "type": "string" }, "netAmount": { "type": "integer" }, "taxAmount": { "type": "integer" }, "payableAmount": { "type": "integer" } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "deliveredAt": { "type": "string" }, "attempts": { "type": "integer" }, "lastAttemptAt": { "type": "string" } } }, "files": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string" }, "transactionId": { "type": "string" }, "tenantId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "direction": { "type": "string" }, "environment": { "type": "string" }, "transactionType": { "type": "string" }, "fileType": { "type": "string" }, "role": { "type": "string" }, "originalName": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "sha256": { "type": "string" }, "source": { "type": "string" }, "parentTransactionId": { "type": "string" }, "apTddTransactionId": { "type": "string" }, "apCoreMessageId": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "storageProvider": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "encryption": { "type": "object", "properties": { "mode": { "type": "string" } } }, "legacyLocalPathPending": { "type": "boolean" } } } }, "statusEvents": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "transactionId": { "type": "string" }, "tenantId": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "detail": { "type": "string" }, "actor": { "type": "string" }, "createdAt": { "type": "string" } } } }, "ap": { "type": "object", "properties": { "linked": { "type": "boolean" }, "apTransactionId": { "type": "string" }, "archived": { "type": "boolean" }, "direction": { "type": "string" }, "apStatus": { "type": "string" }, "docTypeId": { "type": "string" }, "processId": { "type": "string" }, "sender": { "type": "string" }, "receiver": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "as4MessageId": { "type": "string" }, "correlationId": { "type": "string" }, "platformTransactionId": { "type": "string" }, "mlsStatus": { "type": "string" }, "mlsType": { "type": "string" }, "mlsReceivedAt": { "type": "string" }, "mlsId": { "type": "string" }, "mlsErrorCode": { "type": "null" }, "mlsErrorMessage": { "type": "null" }, "mlsResponseCode": { "type": "null" }, "attemptCount": { "type": "integer" }, "lastAttemptAt": { "type": "string" }, "tddStatus": { "type": "null" }, "createdAt": { "type": "string" }, "completedAt": { "type": "string" }, "errorDetails": { "type": "null" }, "documentSize": { "type": "integer" }, "isTdd": { "type": "boolean" } } }, "availability": { "type": "object", "properties": { "payloadAvailable": { "type": "boolean" }, "payloadStatus": { "type": "string" }, "xmlDownloadable": { "type": "boolean" }, "objectStorageIndexed": { "type": "boolean" }, "s3Indexed": { "type": "boolean" }, "fileCount": { "type": "integer" }, "primaryFileId": { "type": "string" }, "storageError": { "type": "null" } } }, "documents": { "type": "object", "properties": { "invoiceXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "string" } } }, "invoicePdf": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "null" }, "fileName": { "type": "null" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "null" }, "reason": { "type": "string" } } }, "sbdXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "null" }, "fileName": { "type": "null" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "null" }, "reason": { "type": "string" } } }, "tddXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "string" } } }, "mlsXml": { "type": "object", "properties": { "available": { "type": "boolean" }, "fileId": { "type": "null" }, "fileName": { "type": "null" }, "contentType": { "type": "string" }, "downloadUrl": { "type": "null" }, "reason": { "type": "string" } } } } }, "documentKind": { "type": "string" }, "statusDetail": { "type": "object", "properties": { "documentKind": { "type": "string" }, "overall": { "type": "string" }, "processing": { "type": "object", "properties": { "platformStatus": { "type": "string" }, "apStatus": { "type": "string" }, "source": { "type": "string" }, "createdAt": { "type": "string" }, "failureStage": { "type": "null" } } }, "validation": { "type": "object", "properties": { "state": { "type": "string" }, "engine": { "type": "string" }, "at": { "type": "string" }, "warnings": { "type": "integer" }, "error": { "type": "null" } } }, "delivery": { "type": "object", "properties": { "state": { "type": "string" }, "apStatus": { "type": "string" }, "platformStatus": { "type": "string" }, "attempts": { "type": "integer" }, "lastAttemptAt": { "type": "string" }, "completedAt": { "type": "string" }, "failedAt": { "type": "null" }, "errorCode": { "type": "null" }, "error": { "type": "null" } } }, "mls": { "type": "object", "properties": { "role": { "type": "string" }, "state": { "type": "string" }, "code": { "type": "string" }, "raw": { "type": "string" }, "at": { "type": "string" }, "mlsId": { "type": "string" }, "errorCode": { "type": "null" }, "errorMessage": { "type": "null" }, "policy": { "type": "string" } } }, "reporting": { "type": "object", "properties": { "state": { "type": "string" }, "raw": { "type": "string" }, "typeCode": { "type": "string" }, "at": { "type": "string" }, "error": { "type": "null" }, "followUpStatus": { "type": "null" }, "followUpError": { "type": "null" }, "ftaResponse": { "type": "object", "properties": { "state": { "type": "string" }, "code": { "type": "string" }, "at": { "type": "string" }, "errorMessage": { "type": "null" } } } } } } }, "status": { "type": "string" }, "deliveryStatus": { "type": "string" }, "reportingStatus": { "type": "string" }, "responseStatus": { "type": "string" }, "journey": { "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string" }, "track": { "type": "string" }, "status": { "type": "string" }, "at": { "type": "string" }, "detail": { "type": "string" } } } }, "apLog": { "type": "object", "properties": { "source": { "type": "string" }, "apTransactionId": { "type": "string" }, "apStatus": { "type": "string" }, "as4MessageId": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "correlationId": { "type": "string" }, "mlsStatus": { "type": "string" }, "mlsType": { "type": "string" }, "mlsReceivedAt": { "type": "string" }, "mlsVerdict": { "type": "string" }, "attempts": { "type": "integer" }, "linkState": { "type": "string" }, "failureReason": { "type": "null" }, "failureStage": { "type": "null" } } }, "tdd": { "type": "object", "properties": { "typeCode": { "type": "string" }, "sendStatus": { "type": "string" }, "mlsStatus": { "type": "string" }, "mlsType": { "type": "string" }, "mlsReceivedAt": { "type": "string" }, "mlsVerdict": { "type": "string" }, "error": { "type": "null" }, "followUpStatus": { "type": "null" }, "followUpError": { "type": "null" }, "chain": { "type": "array", "items": { "type": "object", "properties": { "apTransactionId": { "type": "string" }, "typeCode": { "type": "string" }, "sendStatus": { "type": "string" }, "mlsStatus": { "type": "string" }, "mlsReceivedAt": { "type": "string" }, "mlsErrorMessage": { "type": "null" } } } } } } } }, "example": { "transaction": { "transactionId": "txn_1789562400000_9f3a…", "tenantId": "tnt_7Q2X…", "subsidiaryId": "sub_1789…_a1b2", "direction": "outbound", "status": "delivered", "documentType": "invoice", "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "environment": "production", "c1CountryCode": "AE", "sender": { "participantId": "0235:1004****59", "name": "Sample Trading LLC" }, "receiver": { "participantId": "0235:1002****03" }, "correlationId": "cor_1789562400000_4d5e…", "apCoreMessageId": "f0debc61-…@peppol.azdanapps.com", "sbdhInstanceId": "6c1d2e3f-…", "sizeBytes": 18432, "amount": 1050, "currency": "AED", "taxAmount": 50, "taxExclusiveAmount": 1000, "taxBreakdown": [ { "category": "S", "percent": "5", "taxableAmount": 1000, "taxAmount": 50 } ], "document": { "number": "INV-2026-000123", "issueDate": "2026-10-20", "dueDate": "2026-11-19", "currency": "AED", "typeCode": "380", "supplierName": "Sample Trading LLC", "customerName": "Sample Buyer FZ-LLC", "netAmount": 1000, "taxAmount": 50, "payableAmount": 1050 }, "createdAt": "2026-10-20T09:00:00.000Z", "updatedAt": "2026-10-20T09:02:41.000Z", "deliveredAt": "2026-10-20T09:00:04.000Z", "attempts": 1, "lastAttemptAt": "2026-10-20T09:00:02.000Z" }, "files": [ { "fileId": "file_01J9Z3…", "transactionId": "txn_1789562400000_9f3a…", "tenantId": "tnt_7Q2X…", "subsidiaryId": "sub_1789…_a1b2", "direction": "outbound", "environment": "production", "transactionType": "", "fileType": "payload", "role": "payload", "originalName": "txn_1789562400000_9f3a….xml", "filename": "txn_1789562400000_9f3a….xml", "contentType": "application/xml", "sizeBytes": 18432, "sha256": "3f7a9c…", "source": "", "parentTransactionId": "", "apTddTransactionId": "", "apCoreMessageId": "", "sbdhInstanceId": "", "storageProvider": "oci", "status": "uploaded", "createdAt": "2026-10-20T09:00:01.000Z", "updatedAt": "2026-10-20T09:00:01.000Z", "encryption": { "mode": "NONE" }, "legacyLocalPathPending": false }, { "fileId": "file_01J9Z5…", "transactionId": "txn_1789562400000_9f3a…", "tenantId": "tnt_7Q2X…", "subsidiaryId": "sub_1789…_a1b2", "direction": "outbound", "environment": "production", "transactionType": "taxdata", "fileType": "tdd_xml", "role": "tdd_xml", "originalName": "6c1d2e3f-….xml", "filename": "6c1d2e3f-….xml", "contentType": "application/xml", "sizeBytes": 4210, "sha256": "a91e04…", "source": "ap_core_generated_tdd", "parentTransactionId": "txn_1789562400000_9f3a…", "apTddTransactionId": "b7e2c1d0-…", "apCoreMessageId": "2a4b6c8d-…@peppol.azdanapps.com", "sbdhInstanceId": "9d8c7b6a-…", "storageProvider": "oci", "status": "uploaded", "createdAt": "2026-10-20T09:03:12.000Z", "updatedAt": "2026-10-20T09:03:12.000Z", "encryption": { "mode": "NONE" }, "legacyLocalPathPending": false } ], "statusEvents": [ { "_id": "671f7e…", "transactionId": "txn_1789562400000_9f3a…", "tenantId": "tnt_7Q2X…", "type": "status", "status": "delivered", "detail": "AP Core reported sent", "actor": "system", "createdAt": "2026-10-20T09:00:04.000Z" } ], "ap": { "linked": true, "apTransactionId": "a3c5e7f9-…", "archived": false, "direction": "outbound", "apStatus": "sent", "docTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "sender": "0235:1004****59", "receiver": "0235:1002****03", "sbdhInstanceId": "6c1d2e3f-…", "as4MessageId": "f0debc61-…@peppol.azdanapps.com", "correlationId": "cor_1789562400000_4d5e…", "platformTransactionId": "txn_1789562400000_9f3a…", "mlsStatus": "received_ap", "mlsType": "ALWAYS_SEND", "mlsReceivedAt": "2026-10-20T09:02:40.000Z", "mlsId": "mls-3e1f…", "mlsErrorCode": null, "mlsErrorMessage": null, "mlsResponseCode": null, "attemptCount": 1, "lastAttemptAt": "2026-10-20T09:00:02.000Z", "tddStatus": null, "createdAt": "2026-10-20T09:00:01.000Z", "completedAt": "2026-10-20T09:00:04.000Z", "errorDetails": null, "documentSize": 18432, "isTdd": false }, "availability": { "payloadAvailable": true, "payloadStatus": "uploaded", "xmlDownloadable": true, "objectStorageIndexed": true, "s3Indexed": true, "fileCount": 2, "primaryFileId": "file_01J9Z3…", "storageError": null }, "documents": { "invoiceXml": { "available": true, "fileId": "file_01J9Z3…", "fileName": "txn_1789562400000_9f3a….xml", "contentType": "application/xml", "downloadUrl": "/api/tenant/transactions/txn_1789562400000_9f3a…/files/invoice-xml" }, "invoicePdf": { "available": false, "fileId": null, "fileName": null, "contentType": "application/pdf", "downloadUrl": null, "reason": "not_generated" }, "sbdXml": { "available": false, "fileId": null, "fileName": null, "contentType": "application/xml", "downloadUrl": null, "reason": "not_stored" }, "tddXml": { "available": true, "fileId": "file_01J9Z5…", "fileName": "6c1d2e3f-….xml", "contentType": "application/xml", "downloadUrl": "/api/tenant/transactions/txn_1789562400000_9f3a…/files/tdd-xml" }, "mlsXml": { "available": false, "fileId": null, "fileName": null, "contentType": "application/xml", "downloadUrl": null, "reason": "not_received" } }, "documentKind": "invoice", "statusDetail": { "documentKind": "invoice", "overall": "accepted", "processing": { "platformStatus": "delivered", "apStatus": "sent", "source": "platform+ap", "createdAt": "2026-10-20T09:00:00.000Z", "failureStage": null }, "validation": { "state": "passed", "engine": "internal", "at": "2026-10-20T08:59:59.000Z", "warnings": 0, "error": null }, "delivery": { "state": "delivered", "apStatus": "sent", "platformStatus": "delivered", "attempts": 1, "lastAttemptAt": "2026-10-20T09:00:02.000Z", "completedAt": "2026-10-20T09:00:04.000Z", "failedAt": null, "errorCode": null, "error": null }, "mls": { "role": "received", "state": "accepted", "code": "AP", "raw": "received_ap", "at": "2026-10-20T09:02:40.000Z", "mlsId": "mls-3e1f…", "errorCode": null, "errorMessage": null, "policy": "ALWAYS_SEND" }, "reporting": { "state": "reported", "raw": "sent", "typeCode": "S", "at": "2026-10-20T09:05:30.000Z", "error": null, "followUpStatus": null, "followUpError": null, "ftaResponse": { "state": "accepted", "code": "AP", "at": "2026-10-20T09:05:30.000Z", "errorMessage": null } } }, "status": "delivered", "deliveryStatus": "delivered", "reportingStatus": "reported", "responseStatus": "accepted", "journey": [ { "stage": "validated", "track": "preparation", "status": "complete", "at": "2026-10-20T09:00:00.000Z", "detail": "Schema and PINT rules passed." }, { "stage": "sentAs4", "track": "delivery", "status": "complete", "at": "2026-10-20T09:00:02.000Z", "detail": "Submitted to the Peppol access point via AS4." }, { "stage": "deliveredToAp", "track": "delivery", "status": "complete", "at": "2026-10-20T09:02:41.000Z", "detail": "Delivered to the receiver's access point." }, { "stage": "mlsReceived", "track": "delivery", "status": "complete", "at": "2026-10-20T09:02:40.000Z", "detail": "Positive message level status received from the receiver's access point." }, { "stage": "tddReported", "track": "reporting", "status": "complete", "at": "2026-10-20T09:05:30.000Z", "detail": "Trading document disposition reported to the FTA." }, { "stage": "tddMlsReceived", "track": "reporting", "status": "complete", "at": "2026-10-20T09:05:30.000Z", "detail": "Positive message level status received from the FTA for the tax report." } ], "apLog": { "source": "ap-core", "apTransactionId": "a3c5e7f9-…", "apStatus": "sent", "as4MessageId": "f0debc61-…@peppol.azdanapps.com", "sbdhInstanceId": "6c1d2e3f-…", "correlationId": "cor_1789562400000_4d5e…", "mlsStatus": "received_ap", "mlsType": "ALWAYS_SEND", "mlsReceivedAt": "2026-10-20T09:02:40.000Z", "mlsVerdict": "accepted", "attempts": 1, "linkState": "linked", "failureReason": null, "failureStage": null }, "tdd": { "typeCode": "S", "sendStatus": "sent", "mlsStatus": "received_ap", "mlsType": "ALWAYS_SEND", "mlsReceivedAt": "2026-10-20T09:05:30.000Z", "mlsVerdict": "accepted", "error": null, "followUpStatus": null, "followUpError": null, "chain": [ { "apTransactionId": "b7e2c1d0-…", "typeCode": "S", "sendStatus": "sent", "mlsStatus": "received_ap", "mlsReceivedAt": "2026-10-20T09:05:30.000Z", "mlsErrorMessage": null } ] } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/transactions/{transactionId}/webhooks": { "get": { "operationId": "getTenantTransactionsByTransactionIdWebhooks", "summary": "List the webhook events and deliveries of a transaction", "description": "The webhook side of one transaction of the tenant: its outbox events (one per target webhook, with queue status, attempts, last error and next dispatch time) and the delivery attempts made for them, newest first. AP-keyed events are found by the transaction's correlation, SBDH and AS4 ids too. Never includes payloads.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Transactions" ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Events and attempts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionId": { "type": "string" }, "events": { "type": "array", "items": { "type": "object", "properties": { "eventId": { "type": "string" }, "outboxEventId": { "type": "string" }, "webhookId": { "type": "string" }, "tenantId": { "type": "string" }, "transactionId": { "type": "string" }, "eventType": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "lastError": { "type": "string" }, "nextDispatchAt": { "type": "string" }, "createdAt": { "type": "string" }, "deliveredAt": { "type": "null" }, "deadAt": { "type": "string" } } } }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "attemptId": { "type": "string" }, "webhookId": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string" }, "deliveryStatus": { "type": "string" }, "outcome": { "type": "string" }, "httpStatus": { "type": "integer" }, "latencyMs": { "type": "integer" }, "attempt": { "type": "integer" }, "repeatCount": { "type": "integer" }, "lastAttemptAt": { "type": "null" }, "urlHost": { "type": "string" }, "errorCode": { "type": "null" }, "transactionId": { "type": "string" }, "metadata": { "type": "object", "properties": {} }, "createdAt": { "type": "string" }, "queueStatus": { "type": "string" }, "attemptsTotal": { "type": "integer" }, "nextRetryAt": { "type": "null" }, "deadAt": { "type": "null" } } } } } }, "example": { "transactionId": "txn_1789562400000_9f3a…", "events": [ { "eventId": "evt_ap_9c1d2e3f4a5b6c7d", "outboxEventId": "evt_ap_9c1d2e3f4a5b6c7d:whk_1789562400000_k3j9a1", "webhookId": "whk_1789562400000_k3j9a1", "tenantId": "tnt_7Q2X…", "transactionId": "txn_1789562400000_9f3a…", "eventType": "ap.outbound.delivered", "status": "dead", "attempts": 8, "lastError": "http_503", "nextDispatchAt": "2026-10-20T11:02:45.000Z", "createdAt": "2026-10-20T09:02:45.000Z", "deliveredAt": null, "deadAt": "2026-10-20T11:10:12.000Z" } ], "attempts": [ { "attemptId": "att_1789562565000_4f2a", "webhookId": "whk_1789562400000_k3j9a1", "eventId": "evt_1789562560000_9c1d", "eventType": "transaction.delivered", "deliveryStatus": "delivered", "outcome": "success", "httpStatus": 200, "latencyMs": 184, "attempt": 1, "repeatCount": 1, "lastAttemptAt": null, "urlHost": "erp.example.com", "errorCode": null, "transactionId": "txn_1789562400000_9f3a…", "metadata": {}, "createdAt": "2026-10-20T09:02:45.000Z", "queueStatus": "delivered", "attemptsTotal": 1, "nextRetryAt": null, "deadAt": null } ] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/transactions/{transactionId}/retry": { "post": { "operationId": "postTenantTransactionsByTransactionIdRetry", "summary": "Mark a failed transaction as queued for retry", "description": "Bookkeeping only: for a platform transaction whose status is in the FAILED group, sets `status` to `queued`, increments `attempts`, stamps `lastAttemptAt` and sets `nextRetryAt` (30 s backoff doubling per attempt, capped at 30 min), and writes a `transaction.retry` audit row. It does not call AP Core or resend the document, and no worker in the Platform API reads `nextRetryAt`; when the transaction sweeper is enabled it moves a `queued` outbound row older than 5 minutes back to `failed` (`queued_timeout`). AP-only ids answer 404. Not narrowed by a `tenant_user`'s company scope. To actually resend, submit again through `POST /api/tenant/invoices/send` with the same `Idempotency-Key`.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Transactions" ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "The row is now `queued`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "transactionId": { "type": "string" }, "attempts": { "type": "integer" }, "nextRetryAt": { "type": "string" } } }, "example": { "ok": true, "transactionId": "txn_1789562400000_9f3a…", "attempts": 2, "nextRetryAt": "2026-10-24T10:01:00.000Z" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "409": { "description": "The transaction is not in a failed state (`NOT_RETRYABLE`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "currentStatus": { "type": "string" } } } } }, "example": { "error": { "code": "NOT_RETRYABLE", "currentStatus": "delivered" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/reports/submission": { "get": { "operationId": "getTenantReportsSubmission", "summary": "Get the submission report", "description": "Delivered / failed / pending counts, delivery rate and total amount, a per-day series (last 60 days with data), totals per document type and one row per document, computed from up to 400 of the tenant's most recent business documents (the transaction list with `view=documents`, AP-enriched). The status is MLS-aware: a positive MLS counts as delivered, a negative one as failed. Amounts are the `amount` captured at submit (0 when missing). `from` / `to` are calendar dates or ISO date-times; `to` is inclusive (the whole day). `subsidiaryId=all` means no company filter. tenant_user callers only see rows of their allowed companies / Peppol identities.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "subsidiaryId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The submission report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "submitted": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" }, "deliveryRatePct": { "type": "integer" }, "totalAmount": { "type": "number" } } }, "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" } } } }, "byType": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" }, "amount": { "type": "number" } } } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string" }, "type": { "type": "string" }, "companyName": { "type": "string" }, "counterparty": { "type": "string" }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string" }, "mlsStatus": { "type": "string" }, "tddStatus": { "type": "string" } } } } } }, "example": { "stats": { "submitted": 128, "delivered": 121, "failed": 3, "pending": 4, "deliveryRatePct": 95, "totalAmount": 512340.5 }, "series": [ { "date": "2026-10-20", "delivered": 9, "failed": 0, "pending": 1 } ], "byType": [ { "type": "Invoice", "count": 120, "amount": 530100.5 }, { "type": "CreditNote", "count": 8, "amount": 17760 } ], "rows": [ { "id": "txn_1789562400000_9f3a…", "date": "2026-10-20T09:00:00.000Z", "type": "Invoice", "companyName": "Sample Trading", "counterparty": "0235:1002****03", "amount": 1050, "currency": "AED", "status": "delivered", "mlsStatus": "acknowledged", "tddStatus": "pending" } ] } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/reports/reconciliation": { "get": { "operationId": "getTenantReportsReconciliation", "summary": "Get the reconciliation report", "description": "Four control stages (`source`, `platform`, `peppol`, `fta`) with counts and amounts, and the mismatches: `not_delivered` (failed, or pending for 24 h or more) and `missing_tdd` (delivered but no TDD filed — no `tdd_xml` file and no AP TDD fields). There is no ERP feed, so `source` mirrors `platform`. Computed from up to 1,000 recent business documents. `matchedPct` is the share that passed every control. `from` / `to` are calendar dates or ISO date-times; `to` is inclusive (the whole day). `subsidiaryId=all` means no company filter. tenant_user callers only see rows of their allowed companies / Peppol identities.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "subsidiaryId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The reconciliation report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "matchedPct": { "type": "number" }, "totalDocs": { "type": "integer" }, "mismatchCount": { "type": "integer" }, "varianceAmount": { "type": "integer" } } }, "controls": { "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string" }, "count": { "type": "integer" }, "amount": { "type": "number" } } } }, "mismatches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "transactionId": { "type": "string" }, "issue": { "type": "string" }, "presence": { "type": "object", "properties": { "source": { "type": "boolean" }, "platform": { "type": "boolean" }, "peppol": { "type": "boolean" }, "fta": { "type": "boolean" } } }, "amount": { "type": "integer" }, "ageHours": { "type": "integer" }, "companyName": { "type": "string" }, "detail": { "type": "string" } } } } } }, "example": { "summary": { "matchedPct": 93.8, "totalDocs": 128, "mismatchCount": 8, "varianceAmount": 21450 }, "controls": [ { "stage": "source", "count": 128, "amount": 512340.5 }, { "stage": "platform", "count": 128, "amount": 512340.5 }, { "stage": "peppol", "count": 121, "amount": 498010 }, { "stage": "fta", "count": 120, "amount": 496960 } ], "mismatches": [ { "id": "MISM-001", "transactionId": "txn_1789…_c4d1", "issue": "missing_tdd", "presence": { "source": true, "platform": true, "peppol": true, "fta": false }, "amount": 1050, "ageHours": 30, "companyName": "Sample Trading", "detail": "Delivered over Peppol but the tax data document was never filed with the FTA." } ] } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/reports/exception-aging": { "get": { "operationId": "getTenantReportsExceptionAging", "summary": "Get the exception aging report", "description": "How long exceptions have been open: failed business documents (MLS-aware) plus open / claimed quarantined inbound documents, bucketed by age (`0-24h`, `1-2d`, `2-7d`, `>7d`, always all four), grouped per company (oldest first) and listed oldest first. Quarantined documents carry no company or amount (amount 0, company \"—\") and are left out when a specific `subsidiaryId` is requested. Computed from up to 1,000 recent business documents and up to 500 quarantined documents. `from` / `to` are calendar dates or ISO date-times; `to` is inclusive (the whole day). `subsidiaryId=all` means no company filter. tenant_user callers only see rows of their allowed companies / Peppol identities.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "subsidiaryId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The exception aging report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "open": { "type": "integer" }, "agedOver24h": { "type": "integer" }, "agedOver7d": { "type": "integer" }, "totalAmount": { "type": "integer" } } }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "count": { "type": "integer" }, "amount": { "type": "integer" } } } }, "byCompany": { "type": "array", "items": { "type": "object", "properties": { "subsidiaryId": { "type": "string" }, "companyName": { "type": "string" }, "count": { "type": "integer" }, "amount": { "type": "integer" }, "oldestHours": { "type": "integer" } } } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "date": { "type": "string" }, "companyName": { "type": "string" }, "counterparty": { "type": "string" }, "amount": { "type": "integer" }, "ageHours": { "type": "integer" }, "reason": { "type": "string" } } } } } }, "example": { "stats": { "open": 5, "agedOver24h": 3, "agedOver7d": 1, "totalAmount": 7350 }, "buckets": [ { "key": "0-24h", "count": 2, "amount": 2100 }, { "key": "1-2d", "count": 1, "amount": 0 }, { "key": "2-7d", "count": 1, "amount": 4200 }, { "key": ">7d", "count": 1, "amount": 1050 } ], "byCompany": [ { "subsidiaryId": "sub_1789…_a1b2", "companyName": "Sample Trading", "count": 4, "amount": 7350, "oldestHours": 190 } ], "rows": [ { "id": "txn_1789…_e2f3", "type": "failed", "date": "2026-10-16T12:00:00.000Z", "companyName": "Sample Trading", "counterparty": "0235:1002****03", "amount": 1050, "ageHours": 190, "reason": "Receiver endpoint not found in SMP (ap_core_response)" } ] } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/reports/tdd-status": { "get": { "operationId": "getTenantReportsTddStatus", "summary": "Get the TDD / FTA reporting status report", "description": "For every delivered business document, where its Tax Data Document stands: `failed` (the TDD's own AP transaction failed or the FTA rejected it), `acked` (FTA MLS accepted), `pending` (TDD in flight), `filed` (a TDD exists but its AP row could not be linked) or `missing`. Rows are sorted worst first; `reportingLatencyMs` is TDD time minus delivery time. Pending rows are not counted in `stats`. Computed from up to 1,000 recent business documents. `from` / `to` are calendar dates or ISO date-times; `to` is inclusive (the whole day). `subsidiaryId=all` means no company filter. tenant_user callers only see rows of their allowed companies / Peppol identities.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "subsidiaryId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The TDD status report.", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "delivered": { "type": "integer" }, "acked": { "type": "integer" }, "filed": { "type": "integer" }, "failed": { "type": "integer" }, "missing": { "type": "integer" }, "avgReportingLatencyMs": { "type": "integer" } } }, "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string" }, "companyName": { "type": "string" }, "counterparty": { "type": "string" }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "tddStatus": { "type": "string" }, "tddFiledAt": { "type": "string" }, "tddMlsReceivedAt": { "type": "string" }, "reportingLatencyMs": { "type": "integer" }, "error": { "type": "string" } } } } } }, "example": { "stats": { "delivered": 121, "acked": 117, "filed": 1, "failed": 1, "missing": 1, "avgReportingLatencyMs": 172000 }, "rows": [ { "id": "txn_1789…_a7b8", "date": "2026-10-18T10:00:00.000Z", "companyName": "Sample Trading", "counterparty": "0235:1002****03", "amount": 2100, "currency": "AED", "tddStatus": "failed", "tddFiledAt": "2026-10-18T10:03:00.000Z", "tddMlsReceivedAt": "2026-10-18T10:04:10.000Z", "reportingLatencyMs": 240000, "error": "Rejected by FTA: invalid buyer TIN" }, { "id": "txn_1789562400000_9f3a…", "date": "2026-10-20T09:00:00.000Z", "companyName": "Sample Trading", "counterparty": "0235:1002****03", "amount": 1050, "currency": "AED", "tddStatus": "acked", "tddFiledAt": "2026-10-20T09:03:12.000Z", "tddMlsReceivedAt": "2026-10-20T09:05:30.000Z", "reportingLatencyMs": 170000, "error": null } ] } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/reports/vat-summary": { "get": { "operationId": "getTenantReportsVatSummary", "summary": "Get the VAT summary report", "description": "VAT totals from the tax fields captured at submit time (`taxAmount`, `taxExclusiveAmount`, `taxBreakdown`); VAT is never estimated — `coverage` says how many documents carry tax data. Credit notes are subtracted. Broken down by month, by VAT category / rate (documents without a breakdown under `(unclassified)`) and by company. Computed from up to 1,000 recent business documents. `from` / `to` are calendar dates or ISO date-times; `to` is inclusive (the whole day). `subsidiaryId=all` means no company filter. tenant_user callers only see rows of their allowed companies / Peppol identities.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "subsidiaryId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The VAT summary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "coverage": { "type": "object", "properties": { "totalDocs": { "type": "integer" }, "docsWithVat": { "type": "integer" }, "pct": { "type": "integer" } } }, "totals": { "type": "object", "properties": { "taxableAmount": { "type": "integer" }, "vatAmount": { "type": "integer" } } }, "byMonth": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "taxableAmount": { "type": "integer" }, "vatAmount": { "type": "integer" }, "docs": { "type": "integer" } } } }, "byCategory": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "percent": { "type": "string" }, "taxableAmount": { "type": "integer" }, "vatAmount": { "type": "integer" }, "docs": { "type": "integer" } } } }, "byCompany": { "type": "array", "items": { "type": "object", "properties": { "subsidiaryId": { "type": "string" }, "companyName": { "type": "string" }, "taxableAmount": { "type": "integer" }, "vatAmount": { "type": "integer" }, "docs": { "type": "integer" } } } } } }, "example": { "coverage": { "totalDocs": 128, "docsWithVat": 119, "pct": 93 }, "totals": { "taxableAmount": 470200, "vatAmount": 23510 }, "byMonth": [ { "month": "2026-10", "taxableAmount": 182000, "vatAmount": 9100, "docs": 46 } ], "byCategory": [ { "category": "S", "percent": "5", "taxableAmount": 465200, "vatAmount": 23260, "docs": 115 } ], "byCompany": [ { "subsidiaryId": "sub_1789…_a1b2", "companyName": "Sample Trading", "taxableAmount": 470200, "vatAmount": 23510, "docs": 119 } ] } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/compliance/detail": { "get": { "operationId": "getTenantComplianceDetail", "summary": "Get the compliance center detail", "description": "Compliance score (0–100) from five dimensions — delivery success, validation pass rate, TDD reporting, SLA compliance (delivery within `SLA_DELIVERY_TARGET_MINUTES`, default 10; TDD within `SLA_TDD_TARGET_MINUTES` of delivery, default 15) and exception hygiene (penalties for open / aged failures and quarantined inbound documents) — plus an 8-week trend, counts, SLA percentiles, bottlenecks and a per-participant breakdown. Without `from`, the scan starts 56 days back; up to 1,000 business documents. `estimatedExposure` is `agedExceptions × 1000 + missingTdd × 100`. `from` / `to` are calendar dates or ISO date-times; `to` is inclusive (the whole day). `subsidiaryId=all` means no company filter. tenant_user callers only see rows of their allowed companies / Peppol identities.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Dashboard & compliance" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "subsidiaryId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The compliance detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "overall": { "type": "integer" }, "dimensions": { "type": "object", "properties": { "deliverySuccess": { "type": "integer" }, "validationPassRate": { "type": "integer" }, "tddReporting": { "type": "integer" }, "slaCompliance": { "type": "integer" }, "exceptionHygiene": { "type": "integer" } } }, "trend": { "type": "array", "items": { "type": "integer" } }, "agedExceptions": { "type": "integer" }, "missingTdd": { "type": "integer" }, "estimatedExposure": { "type": "integer" }, "deliveryRatePct": { "type": "number" }, "counts": { "type": "object", "properties": { "total": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" }, "quarantined": { "type": "integer" }, "openExceptions": { "type": "integer" }, "agedExceptions": { "type": "integer" }, "missingTdd": { "type": "integer" } } }, "sla": { "type": "object", "properties": { "deliveryTargetMinutes": { "type": "integer" }, "tddTargetMinutes": { "type": "integer" }, "checks": { "type": "integer" }, "passes": { "type": "integer" }, "compliancePct": { "type": "integer" }, "deliveryMeasured": { "type": "integer" }, "deliveryP50Ms": { "type": "integer" }, "deliveryP95Ms": { "type": "integer" }, "tddMeasured": { "type": "integer" }, "tddP50Ms": { "type": "integer" }, "tddP95Ms": { "type": "integer" } } }, "bottlenecks": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "count": { "type": "integer" } } } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "peppolId": { "type": "string" }, "label": { "type": "string" }, "subsidiaryId": { "type": "string" }, "overall": { "type": "integer" }, "dimensions": { "type": "object", "properties": { "deliverySuccess": { "type": "integer" }, "validationPassRate": { "type": "integer" }, "tddReporting": { "type": "integer" }, "slaCompliance": { "type": "integer" }, "exceptionHygiene": { "type": "integer" } } }, "counts": { "type": "object", "properties": { "total": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "pending": { "type": "integer" }, "quarantined": { "type": "integer" }, "openExceptions": { "type": "integer" }, "agedExceptions": { "type": "integer" }, "missingTdd": { "type": "integer" } } }, "sla": { "type": "object", "properties": { "deliveryTargetMinutes": { "type": "integer" }, "tddTargetMinutes": { "type": "integer" }, "checks": { "type": "integer" }, "passes": { "type": "integer" }, "compliancePct": { "type": "integer" }, "deliveryMeasured": { "type": "integer" }, "deliveryP50Ms": { "type": "integer" }, "deliveryP95Ms": { "type": "integer" }, "tddMeasured": { "type": "integer" }, "tddP50Ms": { "type": "integer" }, "tddP95Ms": { "type": "integer" } } } } } } } }, "example": { "overall": 92, "dimensions": { "deliverySuccess": 98, "validationPassRate": 100, "tddReporting": 97, "slaCompliance": 90, "exceptionHygiene": 75 }, "trend": [ 88, 90, 91, 91, 93, 92, 94, 93 ], "agedExceptions": 1, "missingTdd": 3, "estimatedExposure": 1300, "deliveryRatePct": 94.5, "counts": { "total": 128, "delivered": 121, "failed": 3, "pending": 4, "quarantined": 1, "openExceptions": 4, "agedExceptions": 1, "missingTdd": 3 }, "sla": { "deliveryTargetMinutes": 10, "tddTargetMinutes": 15, "checks": 230, "passes": 207, "compliancePct": 90, "deliveryMeasured": 112, "deliveryP50Ms": 4100, "deliveryP95Ms": 186000, "tddMeasured": 118, "tddP50Ms": 150000, "tddP95Ms": 1260000 }, "bottlenecks": [ { "key": "slowTdd", "count": 14 }, { "key": "missingTdd", "count": 3 } ], "participants": [ { "peppolId": "0235:1004****59", "label": "Production TRN", "subsidiaryId": "sub_1789…_a1b2", "overall": 92, "dimensions": { "deliverySuccess": 98, "validationPassRate": 100, "tddReporting": 97, "slaCompliance": 90, "exceptionHygiene": 85 }, "counts": { "total": 128, "delivered": 121, "failed": 3, "pending": 4, "quarantined": 0, "openExceptions": 3, "agedExceptions": 0, "missingTdd": 3 }, "sla": { "deliveryTargetMinutes": 10, "tddTargetMinutes": 15, "checks": 230, "passes": 207, "compliancePct": 90, "deliveryMeasured": 112, "deliveryP50Ms": 4100, "deliveryP95Ms": 186000, "tddMeasured": 118, "tddP50Ms": 150000, "tddP95Ms": 1260000 } } ] } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/compliance/score": { "get": { "operationId": "getTenantComplianceScore", "summary": "Get the compliance score", "description": "The overall score and three of the dimensions of `GET /api/tenant/compliance/detail` (same computation, same query), for the dashboard ring. `from` / `to` are calendar dates or ISO date-times; `to` is inclusive (the whole day). `subsidiaryId=all` means no company filter. tenant_user callers only see rows of their allowed companies / Peppol identities.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Dashboard & compliance" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "subsidiaryId", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The compliance score.", "content": { "application/json": { "schema": { "type": "object", "properties": { "overall": { "type": "integer" }, "deliverySuccess": { "type": "integer" }, "validationPassRate": { "type": "integer" }, "slaCompliance": { "type": "integer" } } }, "example": { "overall": 92, "deliverySuccess": 98, "validationPassRate": 100, "slaCompliance": 90 } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/files": { "get": { "operationId": "getTenantFiles", "summary": "List the tenant's stored files", "description": "Paged `transaction_files` rows of the tenant, newest first, in the tenant-safe projection. Filters: `transactionId` (exact match on the row's own `transactionId`) and `role`. A `tenant_user` sees files of allowed companies and files of (or generated for) transactions in their scope.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Documents & files" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 } }, { "name": "transactionId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "payload", "mlr", "mdn", "envelope", "attachment" ] } }, { "name": "fileType", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 40 } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } } ], "responses": { "200": { "description": "One page of files.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string" }, "transactionId": { "type": "string" }, "tenantId": { "type": "string" }, "subsidiaryId": { "type": "string" }, "direction": { "type": "string" }, "environment": { "type": "string" }, "transactionType": { "type": "string" }, "fileType": { "type": "string" }, "role": { "type": "string" }, "originalName": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "sha256": { "type": "string" }, "source": { "type": "string" }, "parentTransactionId": { "type": "string" }, "apTddTransactionId": { "type": "string" }, "apCoreMessageId": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "storageProvider": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "encryption": { "type": "object", "properties": { "mode": { "type": "string" } } }, "legacyLocalPathPending": { "type": "boolean" } } } }, "page": { "type": "object", "properties": { "number": { "type": "integer" }, "size": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } }, "example": { "items": [ { "fileId": "file_01J9Z5…", "transactionId": "txn_1789562400000_9f3a…", "tenantId": "tnt_7Q2X…", "subsidiaryId": "sub_1789…_a1b2", "direction": "outbound", "environment": "production", "transactionType": "taxdata", "fileType": "tdd_xml", "role": "tdd_xml", "originalName": "6c1d2e3f-….xml", "filename": "6c1d2e3f-….xml", "contentType": "application/xml", "sizeBytes": 4210, "sha256": "a91e04…", "source": "ap_core_generated_tdd", "parentTransactionId": "txn_1789562400000_9f3a…", "apTddTransactionId": "b7e2c1d0-…", "apCoreMessageId": "2a4b6c8d-…@peppol.azdanapps.com", "sbdhInstanceId": "9d8c7b6a-…", "storageProvider": "oci", "status": "uploaded", "createdAt": "2026-10-20T09:03:12.000Z", "updatedAt": "2026-10-20T09:03:12.000Z", "encryption": { "mode": "NONE" }, "legacyLocalPathPending": false }, { "fileId": "file_01J9Z3…", "transactionId": "txn_1789562400000_9f3a…", "tenantId": "tnt_7Q2X…", "subsidiaryId": "sub_1789…_a1b2", "direction": "outbound", "environment": "production", "transactionType": "", "fileType": "payload", "role": "payload", "originalName": "txn_1789562400000_9f3a….xml", "filename": "txn_1789562400000_9f3a….xml", "contentType": "application/xml", "sizeBytes": 18432, "sha256": "3f7a9c…", "source": "", "parentTransactionId": "", "apTddTransactionId": "", "apCoreMessageId": "", "sbdhInstanceId": "", "storageProvider": "oci", "status": "uploaded", "createdAt": "2026-10-20T09:00:01.000Z", "updatedAt": "2026-10-20T09:00:01.000Z", "encryption": { "mode": "NONE" }, "legacyLocalPathPending": false } ], "page": { "number": 1, "size": 25, "total": 2, "totalPages": 1 } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/webhooks": { "get": { "operationId": "getTenantWebhooks", "summary": "List webhooks", "description": "The tenant's webhook configurations. Signing secrets are never returned (`hasSigningSecret` says whether one is set); outbound authentication is shown redacted (`auth.type`, `configured`, a masked `display`).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "The webhooks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "webhookId": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "subsidiaryId": { "type": "null" }, "payloadVersion": { "type": "string" }, "status": { "type": "string" }, "signingSecretRotatedAt": { "type": "null" }, "previousSecretValidUntil": { "type": "null" }, "health": { "type": "object", "properties": { "consecutiveFailures": { "type": "integer" }, "successRate24h": { "type": "integer" }, "lastDeliveryAt": { "type": "string" }, "lastSuccessAt": { "type": "string" } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "hasSigningSecret": { "type": "boolean" }, "auth": { "type": "object", "properties": { "type": { "type": "string" }, "configured": { "type": "boolean" }, "display": { "type": "string" } } } } } } } }, "example": { "items": [ { "_id": "671f3a…", "webhookId": "whk_1789562400000_k3j9a1", "tenantId": "tnt_7Q2X…", "name": "ERP production", "url": "https://erp.example.com/hooks/azdan", "events": [ "document.delivered", "document.failed", "mls.rejected" ], "subsidiaryId": null, "payloadVersion": "2", "status": "active", "signingSecretRotatedAt": null, "previousSecretValidUntil": null, "health": { "consecutiveFailures": 0, "successRate24h": 1, "lastDeliveryAt": "2026-10-20T09:02:45.000Z", "lastSuccessAt": "2026-10-20T09:02:45.000Z" }, "createdAt": "2026-09-02T10:00:00.000Z", "updatedAt": "2026-10-01T11:30:00.000Z", "hasSigningSecret": true, "auth": { "type": "bearer", "configured": true, "display": "Bearer ••••••••••••" } } ] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "post": { "operationId": "postTenantWebhooks", "summary": "Create a webhook", "description": "Registers an HTTPS endpoint for event notifications. The URL is checked against the outbound URL policy — https only, no credentials, no private, loopback, link-local or metadata address, and the host must not resolve to one (400 with the rejection `code` and `hint`, e.g. `HTTPS_REQUIRED`, `PRIVATE_IP`, `DNS_PRIVATE`). `events` lists topics by their v2 or legacy name (see `GET …/webhooks/events`) and defaults to `[\"*\"]`. `name` is a label; `subsidiaryId` scopes the webhook to one company of the tenant (null = all); `payloadVersion` chooses the envelope (`\"2\"`, the default for new webhooks, or `\"1\"` for receivers written against the original one). A signing secret is generated unless `generateSecret` is `false`; it is returned **once** in `revealedSecret` and only a hash plus an encrypted copy (used to sign deliveries) are stored. Optional outbound `auth` (bearer, basic, API key header, custom headers, OAuth2 client credentials, NetSuite OAuth 2.0) is validated and stored encrypted; responses only show it redacted. Audit-logged (`webhook.create`).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "default": [ "*" ] }, "generateSecret": { "type": "boolean" }, "name": { "type": "string", "maxLength": 80 }, "subsidiaryId": { "type": [ "string", "null" ], "maxLength": 64 }, "payloadVersion": { "type": "string", "enum": [ "1", "2" ] }, "auth": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "bearer", "basic", "apiKey", "customHeaders", "oauth2ClientCredentials", "netsuiteOauth2" ] }, "token": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "headerName": { "type": "string" }, "headerValue": { "type": "string" }, "headers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] } }, "tokenUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "scope": { "type": "string" }, "audience": { "type": "string" }, "authMethod": { "type": "string", "enum": [ "client_secret_basic", "client_secret_post" ] }, "connectionId": { "type": "string" } }, "required": [ "type" ] } }, "required": [ "url" ] }, "example": { "name": "ERP production", "url": "https://erp.example.com/hooks/azdan", "events": [ "document.delivered", "document.failed", "mls.rejected" ], "subsidiaryId": null, "payloadVersion": "2", "generateSecret": true, "auth": { "type": "bearer", "token": "…" } } } } }, "responses": { "201": { "description": "Created. The signing secret is returned only in this response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string" }, "webhookId": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "subsidiaryId": { "type": "null" }, "payloadVersion": { "type": "string" }, "status": { "type": "string" }, "signingSecretRotatedAt": { "type": "null" }, "previousSecretValidUntil": { "type": "null" }, "health": { "type": "object", "properties": { "consecutiveFailures": { "type": "integer" }, "successRate24h": { "type": "integer" } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "hasSigningSecret": { "type": "boolean" }, "auth": { "type": "object", "properties": { "type": { "type": "string" }, "configured": { "type": "boolean" }, "display": { "type": "string" } } }, "revealedSecret": { "type": "string" } } }, "example": { "_id": "671f3a…", "webhookId": "whk_1789562400000_k3j9a1", "tenantId": "tnt_7Q2X…", "name": "ERP production", "url": "https://erp.example.com/hooks/azdan", "events": [ "document.delivered", "document.failed", "mls.rejected" ], "subsidiaryId": null, "payloadVersion": "2", "status": "active", "signingSecretRotatedAt": null, "previousSecretValidUntil": null, "health": { "consecutiveFailures": 0, "successRate24h": 1 }, "createdAt": "2026-09-02T10:00:00.000Z", "updatedAt": "2026-10-01T11:30:00.000Z", "hasSigningSecret": true, "auth": { "type": "bearer", "configured": true, "display": "Bearer ••••••••••••" }, "revealedSecret": "whs_AbCdEf…" } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/webhooks/deliveries": { "get": { "operationId": "getTenantWebhooksDeliveries", "summary": "List webhook delivery attempts across all webhooks", "description": "Delivery attempts of the tenant's webhooks, newest first, with keyset pagination (`limit` 1–100, opaque `cursor` from `pagination.nextCursor`). Filters: `webhookId` (must belong to the tenant, else 404), `status` (`delivered` or `failed`; `pending`, `in_flight` and `dead` are accepted but return nothing — those states are not recorded as attempts), `eventType`, `dateFrom` / `dateTo`. Each row carries the `transactionId` the event belongs to and where the event stands in the queue now (`queueStatus`, `attemptsTotal`, `nextRetryAt`, `deadAt`). Header and body fields are not exposed; metadata is redacted.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "delivered", "failed", "pending", "in_flight", "dead" ] } }, { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "dateFrom", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "dateTo", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } } ], "responses": { "200": { "description": "One page of delivery attempts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "attemptId": { "type": "string" }, "webhookId": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string" }, "deliveryStatus": { "type": "string" }, "outcome": { "type": "string" }, "httpStatus": { "type": "integer" }, "latencyMs": { "type": "integer" }, "attempt": { "type": "integer" }, "repeatCount": { "type": "integer" }, "lastAttemptAt": { "type": "null" }, "urlHost": { "type": "string" }, "errorCode": { "type": "null" }, "transactionId": { "type": "string" }, "metadata": { "type": "object", "properties": {} }, "createdAt": { "type": "string" }, "queueStatus": { "type": "string" }, "attemptsTotal": { "type": "integer" }, "nextRetryAt": { "type": "null" }, "deadAt": { "type": "null" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "nextCursor": { "type": "string" }, "hasNext": { "type": "boolean" } } } } }, "example": { "items": [ { "attemptId": "att_1789562565000_4f2a", "webhookId": "whk_1789562400000_k3j9a1", "eventId": "evt_1789562560000_9c1d", "eventType": "transaction.delivered", "deliveryStatus": "delivered", "outcome": "success", "httpStatus": 200, "latencyMs": 184, "attempt": 1, "repeatCount": 1, "lastAttemptAt": null, "urlHost": "erp.example.com", "errorCode": null, "transactionId": "txn_1789562400000_9f3a…", "metadata": {}, "createdAt": "2026-10-20T09:02:45.000Z", "queueStatus": "delivered", "attemptsTotal": 1, "nextRetryAt": null, "deadAt": null } ], "pagination": { "limit": 25, "nextCursor": "eyJ0IjoiMjAyNi0xMC0yMFQwOTowMjo0NS4wMDBaIiwiYSI6ImF0dF8…", "hasNext": true } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/webhooks/events": { "get": { "operationId": "getTenantWebhooksEvents", "summary": "List the webhook event types", "description": "The catalogue a webhook can subscribe to: each topic's payload-v2 name (`type`), the legacy v1 name it is also known by (`legacyType`, null for topics introduced with v2), its `group` (documents, transactions, mls, tdd, webhook) and a description. A subscription may use either name; `\"*\"` means every topic.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "responses": { "200": { "description": "The catalogue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "legacyType": { "type": "string" }, "group": { "type": "string" }, "description": { "type": "string" } } } } } }, "example": { "items": [ { "type": "document.delivered", "legacyType": "ap.outbound.delivered", "group": "documents", "description": "The receiving access point confirmed delivery (AS4 receipt)." }, { "type": "mls.rejected", "legacyType": null, "group": "mls", "description": "The receiver's access point rejected the document: MLS status RE, with the reason." } ] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/webhooks/dead-letters": { "get": { "operationId": "getTenantWebhooksDeadLetters", "summary": "List dead-lettered webhook events", "description": "Events of the tenant's webhooks that exhausted their delivery attempts or failed permanently (`status=dead`, the default), or the ones still retrying (`status=failed`), newest first, one row per target webhook. Filters: `webhookId`, `eventType` (either name of a topic), `transactionId`, `from` / `to` (event creation time). Page-based (`page`, `pageSize` 1–200). Requeue one with `POST …/deliveries/{eventId}/retry` or all of a webhook's with `POST …/{webhookId}/replay`.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "transactionId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "dead", "failed" ], "default": "dead" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 } } ], "responses": { "200": { "description": "One page of the dead-letter queue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "eventId": { "type": "string" }, "outboxEventId": { "type": "string" }, "webhookId": { "type": "string" }, "tenantId": { "type": "string" }, "transactionId": { "type": "string" }, "eventType": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "lastError": { "type": "string" }, "nextDispatchAt": { "type": "string" }, "createdAt": { "type": "string" }, "deliveredAt": { "type": "null" }, "deadAt": { "type": "string" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" } } }, "example": { "items": [ { "eventId": "evt_ap_9c1d2e3f4a5b6c7d", "outboxEventId": "evt_ap_9c1d2e3f4a5b6c7d:whk_1789562400000_k3j9a1", "webhookId": "whk_1789562400000_k3j9a1", "tenantId": "tnt_7Q2X…", "transactionId": "txn_1789562400000_9f3a…", "eventType": "ap.outbound.delivered", "status": "dead", "attempts": 8, "lastError": "http_503", "nextDispatchAt": "2026-10-20T11:02:45.000Z", "createdAt": "2026-10-20T09:02:45.000Z", "deliveredAt": null, "deadAt": "2026-10-20T11:10:12.000Z" } ], "total": 1, "page": 1, "pageSize": 25 } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/webhooks/deliveries/{eventId}/retry": { "post": { "operationId": "postTenantWebhooksDeliveriesByEventIdRetry", "summary": "Requeue one webhook event", "description": "Puts one event of the tenant back to `pending` for immediate dispatch: every target webhook's copy of it, or only the copy for `webhookId` when given. `eventId` is the public event id (`X-Azdan-Event-Id`) or a target row's own id. Only rows in `failed` or `dead` are touched; attempt counters are kept.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "additionalProperties": false }, "example": { "webhookId": "whk_1789562400000_k3j9a1" } } } }, "responses": { "200": { "description": "What was matched and requeued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "matched": { "type": "integer" }, "requeued": { "type": "integer" }, "eventIds": { "type": "array", "items": { "type": "string" } } } }, "example": { "matched": 1, "requeued": 1, "eventIds": [ "evt_ap_9c1d2e3f4a5b6c7d:whk_1789562400000_k3j9a1" ] } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/webhooks/{webhookId}/deliveries": { "get": { "operationId": "getTenantWebhooksByWebhookIdDeliveries", "summary": "List delivery attempts of one webhook", "description": "Same as `GET /api/tenant/webhooks/deliveries` for one webhook; the path id wins over a `webhookId` query parameter. A webhook of another tenant answers 404.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "webhookId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "delivered", "failed", "pending", "in_flight", "dead" ] } }, { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "dateFrom", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "dateTo", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } } ], "responses": { "200": { "description": "One page of delivery attempts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "attemptId": { "type": "string" }, "webhookId": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string" }, "deliveryStatus": { "type": "string" }, "outcome": { "type": "string" }, "httpStatus": { "type": "integer" }, "latencyMs": { "type": "integer" }, "attempt": { "type": "integer" }, "repeatCount": { "type": "integer" }, "lastAttemptAt": { "type": "null" }, "urlHost": { "type": "string" }, "errorCode": { "type": "null" }, "transactionId": { "type": "string" }, "metadata": { "type": "object", "properties": {} }, "createdAt": { "type": "string" }, "queueStatus": { "type": "string" }, "attemptsTotal": { "type": "integer" }, "nextRetryAt": { "type": "null" }, "deadAt": { "type": "null" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "nextCursor": { "type": "string" }, "hasNext": { "type": "boolean" } } } } }, "example": { "items": [ { "attemptId": "att_1789562565000_4f2a", "webhookId": "whk_1789562400000_k3j9a1", "eventId": "evt_1789562560000_9c1d", "eventType": "transaction.delivered", "deliveryStatus": "delivered", "outcome": "success", "httpStatus": 200, "latencyMs": 184, "attempt": 1, "repeatCount": 1, "lastAttemptAt": null, "urlHost": "erp.example.com", "errorCode": null, "transactionId": "txn_1789562400000_9f3a…", "metadata": {}, "createdAt": "2026-10-20T09:02:45.000Z", "queueStatus": "delivered", "attemptsTotal": 1, "nextRetryAt": null, "deadAt": null } ], "pagination": { "limit": 25, "nextCursor": "eyJ0IjoiMjAyNi0xMC0yMFQwOTowMjo0NS4wMDBaIiwiYSI6ImF0dF8…", "hasNext": true } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/webhooks/{webhookId}": { "get": { "operationId": "getTenantWebhooksByWebhookId", "summary": "Get one webhook", "description": "One webhook of the tenant in the same redacted shape as the list, with its outbox queue counts (`pending`, `in_flight`, `failed`, `delivered`, `dead`) and its ten most recent delivery attempts. A webhook of another tenant answers 404.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "_id": { "type": "string" }, "webhookId": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "subsidiaryId": { "type": "null" }, "payloadVersion": { "type": "string" }, "status": { "type": "string" }, "signingSecretRotatedAt": { "type": "null" }, "previousSecretValidUntil": { "type": "null" }, "health": { "type": "object", "properties": { "consecutiveFailures": { "type": "integer" }, "successRate24h": { "type": "integer" }, "lastDeliveryAt": { "type": "string" }, "lastSuccessAt": { "type": "string" } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "hasSigningSecret": { "type": "boolean" }, "auth": { "type": "object", "properties": { "type": { "type": "string" }, "configured": { "type": "boolean" }, "display": { "type": "string" } } } } }, "queue": { "type": "object", "properties": { "pending": { "type": "integer" }, "in_flight": { "type": "integer" }, "failed": { "type": "integer" }, "delivered": { "type": "integer" }, "dead": { "type": "integer" } } }, "recentAttempts": { "type": "array", "items": { "type": "object", "properties": { "attemptId": { "type": "string" }, "webhookId": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string" }, "deliveryStatus": { "type": "string" }, "outcome": { "type": "string" }, "httpStatus": { "type": "integer" }, "latencyMs": { "type": "integer" }, "attempt": { "type": "integer" }, "repeatCount": { "type": "integer" }, "lastAttemptAt": { "type": "null" }, "urlHost": { "type": "string" }, "errorCode": { "type": "null" }, "transactionId": { "type": "string" }, "metadata": { "type": "object", "properties": {} }, "createdAt": { "type": "string" }, "queueStatus": { "type": "string" }, "attemptsTotal": { "type": "integer" }, "nextRetryAt": { "type": "null" }, "deadAt": { "type": "null" } } } } } }, "example": { "webhook": { "_id": "671f3a…", "webhookId": "whk_1789562400000_k3j9a1", "tenantId": "tnt_7Q2X…", "name": "ERP production", "url": "https://erp.example.com/hooks/azdan", "events": [ "document.delivered", "document.failed", "mls.rejected" ], "subsidiaryId": null, "payloadVersion": "2", "status": "active", "signingSecretRotatedAt": null, "previousSecretValidUntil": null, "health": { "consecutiveFailures": 0, "successRate24h": 1, "lastDeliveryAt": "2026-10-20T09:02:45.000Z", "lastSuccessAt": "2026-10-20T09:02:45.000Z" }, "createdAt": "2026-09-02T10:00:00.000Z", "updatedAt": "2026-10-01T11:30:00.000Z", "hasSigningSecret": true, "auth": { "type": "bearer", "configured": true, "display": "Bearer ••••••••••••" } }, "queue": { "pending": 0, "in_flight": 0, "failed": 1, "delivered": 412, "dead": 2 }, "recentAttempts": [ { "attemptId": "att_1789562565000_4f2a", "webhookId": "whk_1789562400000_k3j9a1", "eventId": "evt_1789562560000_9c1d", "eventType": "transaction.delivered", "deliveryStatus": "delivered", "outcome": "success", "httpStatus": 200, "latencyMs": 184, "attempt": 1, "repeatCount": 1, "lastAttemptAt": null, "urlHost": "erp.example.com", "errorCode": null, "transactionId": "txn_1789562400000_9f3a…", "metadata": {}, "createdAt": "2026-10-20T09:02:45.000Z", "queueStatus": "delivered", "attemptsTotal": 1, "nextRetryAt": null, "deadAt": null } ] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "delete": { "operationId": "deleteTenantWebhooksByWebhookId", "summary": "Delete a webhook", "description": "Permanently deletes the webhook configuration. Delivery history and outbox rows are kept. Audit-logged (`webhook.delete`).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "webhookId": { "type": "string" } } }, "example": { "ok": true, "webhookId": "whk_1789562400000_k3j9a1" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "patch": { "operationId": "patchTenantWebhooksByWebhookId", "summary": "Update a webhook's URL, events, status, name, company or payload version", "description": "Changes any of `url` (re-checked against the outbound URL policy, DNS included), `events`, `status` (`active`, `paused` — a temporary hold — or `disabled` — switched off; both keep events queued and deliver nothing), `name`, `subsidiaryId` (one of the tenant's companies, or null for all) and `payloadVersion` (`\"1\"` or `\"2\"`); at least one is required and unknown fields are rejected. The signing secret is rotated through `POST …/rotate-secret`. Audit-logged (`webhook.update`).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ] }, "name": { "type": "string", "maxLength": 80 }, "subsidiaryId": { "type": [ "string", "null" ], "maxLength": 64 }, "payloadVersion": { "type": "string", "enum": [ "1", "2" ] } }, "additionalProperties": false }, "example": { "status": "paused" } } } }, "responses": { "200": { "description": "The updated webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string" }, "webhookId": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "subsidiaryId": { "type": "null" }, "payloadVersion": { "type": "string" }, "status": { "type": "string" }, "signingSecretRotatedAt": { "type": "null" }, "previousSecretValidUntil": { "type": "null" }, "health": { "type": "object", "properties": { "consecutiveFailures": { "type": "integer" }, "successRate24h": { "type": "integer" }, "lastDeliveryAt": { "type": "string" }, "lastSuccessAt": { "type": "string" } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "hasSigningSecret": { "type": "boolean" }, "auth": { "type": "object", "properties": { "type": { "type": "string" }, "configured": { "type": "boolean" }, "display": { "type": "string" } } } } }, "example": { "_id": "671f3a…", "webhookId": "whk_1789562400000_k3j9a1", "tenantId": "tnt_7Q2X…", "name": "ERP production", "url": "https://erp.example.com/hooks/azdan", "events": [ "document.delivered", "document.failed", "mls.rejected" ], "subsidiaryId": null, "payloadVersion": "2", "status": "paused", "signingSecretRotatedAt": null, "previousSecretValidUntil": null, "health": { "consecutiveFailures": 0, "successRate24h": 1, "lastDeliveryAt": "2026-10-20T09:02:45.000Z", "lastSuccessAt": "2026-10-20T09:02:45.000Z" }, "createdAt": "2026-09-02T10:00:00.000Z", "updatedAt": "2026-10-01T11:30:00.000Z", "hasSigningSecret": true, "auth": { "type": "bearer", "configured": true, "display": "Bearer ••••••••••••" } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/webhooks/{webhookId}/test": { "post": { "operationId": "postTenantWebhooksByWebhookIdTest", "summary": "Send a test event to a webhook", "description": "Queues a `webhook.test` outbox event for this webhook, dispatched by the webhook worker like any other event; the result shows up in the delivery history. The webhook must be `active` (400 otherwise). Audit-logged (`webhook.test_requested`).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "The test event was queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "eventId": { "type": "string" }, "requestId": { "type": "string" }, "webhookId": { "type": "string" }, "status": { "type": "string" } } }, "example": { "ok": true, "eventId": "evt_test_1789562400000_8b7c…", "requestId": "req_4f1e…", "webhookId": "whk_1789562400000_k3j9a1", "status": "queued" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/webhooks/{webhookId}/replay": { "post": { "operationId": "postTenantWebhooksByWebhookIdReplay", "summary": "Replay failed or dead-lettered webhook events", "description": "Puts this webhook's outbox events in status `failed` or `dead` back to `pending` for immediate dispatch, oldest first, up to `limit` (1–1000, default 100); `eventIds` narrows the selection. `dryRun: true` only reports what would be requeued. A webhook of another tenant answers 404.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "maxItems": 1000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "dryRun": { "type": "boolean", "default": false } }, "additionalProperties": false }, "example": { "eventIds": [ "evt_1789562560000_9c1d" ], "limit": 100, "dryRun": false } } } }, "responses": { "200": { "description": "What was matched and requeued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "matched": { "type": "integer" }, "requeued": { "type": "integer" }, "dryRun": { "type": "boolean" }, "eventIds": { "type": "array", "items": { "type": "string" } } } }, "example": { "matched": 1, "requeued": 1, "dryRun": false, "eventIds": [ "evt_1789562560000_9c1d" ] } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/webhooks/{webhookId}/auth": { "delete": { "operationId": "deleteTenantWebhooksByWebhookIdAuth", "summary": "Remove a webhook's outbound authentication", "description": "Resets the webhook's outbound authentication to `none`. Audit-logged (`webhook.auth_clear`).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "The updated webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string" }, "webhookId": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "subsidiaryId": { "type": "null" }, "payloadVersion": { "type": "string" }, "status": { "type": "string" }, "signingSecretRotatedAt": { "type": "null" }, "previousSecretValidUntil": { "type": "null" }, "health": { "type": "object", "properties": { "consecutiveFailures": { "type": "integer" }, "successRate24h": { "type": "integer" }, "lastDeliveryAt": { "type": "string" }, "lastSuccessAt": { "type": "string" } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "hasSigningSecret": { "type": "boolean" }, "auth": { "type": "object", "properties": { "type": { "type": "string" }, "configured": { "type": "boolean" } } } } }, "example": { "_id": "671f3a…", "webhookId": "whk_1789562400000_k3j9a1", "tenantId": "tnt_7Q2X…", "name": "ERP production", "url": "https://erp.example.com/hooks/azdan", "events": [ "document.delivered", "document.failed", "mls.rejected" ], "subsidiaryId": null, "payloadVersion": "2", "status": "active", "signingSecretRotatedAt": null, "previousSecretValidUntil": null, "health": { "consecutiveFailures": 0, "successRate24h": 1, "lastDeliveryAt": "2026-10-20T09:02:45.000Z", "lastSuccessAt": "2026-10-20T09:02:45.000Z" }, "createdAt": "2026-09-02T10:00:00.000Z", "updatedAt": "2026-10-01T11:30:00.000Z", "hasSigningSecret": true, "auth": { "type": "none", "configured": false } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "patch": { "operationId": "patchTenantWebhooksByWebhookIdAuth", "summary": "Set a webhook's outbound authentication", "description": "Replaces how deliveries authenticate to the receiving endpoint (`none`, `bearer`, `basic`, `apiKey`, `customHeaders`, `oauth2ClientCredentials`, `netsuiteOauth2`). Credentials are validated and stored encrypted; the response shows them redacted. Audit-logged (`webhook.auth_update`).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "bearer", "basic", "apiKey", "customHeaders", "oauth2ClientCredentials", "netsuiteOauth2" ] }, "token": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "headerName": { "type": "string" }, "headerValue": { "type": "string" }, "headers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "required": [ "name", "value" ] } }, "tokenUrl": { "type": "string", "format": "uri" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" }, "scope": { "type": "string" }, "audience": { "type": "string" }, "authMethod": { "type": "string", "enum": [ "client_secret_basic", "client_secret_post" ] }, "connectionId": { "type": "string" } }, "required": [ "type" ] }, "example": { "type": "oauth2ClientCredentials", "tokenUrl": "https://auth.example.com/oauth2/token", "clientId": "azdan-hooks", "clientSecret": "…", "scope": "hooks.write", "authMethod": "client_secret_post" } } } }, "responses": { "200": { "description": "The updated webhook.", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string" }, "webhookId": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "subsidiaryId": { "type": "null" }, "payloadVersion": { "type": "string" }, "status": { "type": "string" }, "signingSecretRotatedAt": { "type": "null" }, "previousSecretValidUntil": { "type": "null" }, "health": { "type": "object", "properties": { "consecutiveFailures": { "type": "integer" }, "successRate24h": { "type": "integer" }, "lastDeliveryAt": { "type": "string" }, "lastSuccessAt": { "type": "string" } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "hasSigningSecret": { "type": "boolean" }, "auth": { "type": "object", "properties": { "type": { "type": "string" }, "configured": { "type": "boolean" }, "display": { "type": "string" }, "tokenUrl": { "type": "string" }, "clientId": { "type": "string" }, "scope": { "type": "string" }, "audience": { "type": "null" }, "authMethod": { "type": "string" } } } } }, "example": { "_id": "671f3a…", "webhookId": "whk_1789562400000_k3j9a1", "tenantId": "tnt_7Q2X…", "name": "ERP production", "url": "https://erp.example.com/hooks/azdan", "events": [ "document.delivered", "document.failed", "mls.rejected" ], "subsidiaryId": null, "payloadVersion": "2", "status": "active", "signingSecretRotatedAt": null, "previousSecretValidUntil": null, "health": { "consecutiveFailures": 0, "successRate24h": 1, "lastDeliveryAt": "2026-10-20T09:02:45.000Z", "lastSuccessAt": "2026-10-20T09:02:45.000Z" }, "createdAt": "2026-09-02T10:00:00.000Z", "updatedAt": "2026-10-01T11:30:00.000Z", "hasSigningSecret": true, "auth": { "type": "oauth2ClientCredentials", "configured": true, "display": "OAuth2 (azdan-hooks)", "tokenUrl": "https://auth.example.com/oauth2/token", "clientId": "azdan-hooks", "scope": "hooks.write", "audience": null, "authMethod": "client_secret_post" } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/webhooks/{webhookId}/rotate-secret": { "post": { "operationId": "postTenantWebhooksByWebhookIdRotateSecret", "summary": "Rotate a webhook's signing secret", "description": "Generates a new signing secret, returned **once** in `revealedSecret`. Rotation overlaps: until `previousSecretValidUntil` (24 hours, `WEBHOOK_SECRET_OVERLAP_HOURS`) every delivery carries two `v1=` signatures in `X-Azdan-Signature`, one per secret, so the receiver can switch without a gap; afterwards only the new secret signs. Only a hash and an encrypted copy are stored. Audit-logged (`webhook.rotate_secret`).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "The new secret, shown only in this response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookId": { "type": "string" }, "revealedSecret": { "type": "string" }, "signingSecretRotatedAt": { "type": "string" }, "previousSecretValidUntil": { "type": "string" } } }, "example": { "webhookId": "whk_1789562400000_k3j9a1", "revealedSecret": "whs_AbCdEf…", "signingSecretRotatedAt": "2026-10-24T10:00:00.000Z", "previousSecretValidUntil": "2026-10-25T10:00:00.000Z" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/api-keys": { "get": { "operationId": "getTenantApiKeys", "summary": "List API keys", "description": "The tenant's Integration API keys, active and revoked, without secrets (label, prefix, scopes, status, last use).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Users & API keys" ], "responses": { "200": { "description": "The API keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "apiKeyId": { "type": "string" }, "tenantId": { "type": "string" }, "label": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdBy": { "type": "string" }, "createdAt": { "type": "string" }, "lastUsedAt": { "type": "string" } } } }, "note": { "type": "string" } } }, "example": { "items": [ { "_id": "671f4b…", "apiKeyId": "ak_1789562400000_x7k2p9", "tenantId": "tnt_7Q2X…", "label": "NetSuite production", "prefix": "azd_live_AbCdEf", "scopes": [ "peppol:validate", "peppol:submit", "transactions:read" ], "status": "active", "createdBy": "user_1789…_5e6f", "createdAt": "2026-10-01T07:45:00.000Z", "lastUsedAt": "2026-10-24T07:55:12.000Z" } ], "note": "API keys are listed without secrets. Create a new key to reveal a secret once." } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "post": { "operationId": "postTenantApiKeys", "summary": "Create an API key", "description": "Creates an Integration API key (`azd_live_…`, or `azd_test_…` with `live: false`). The full token is returned **once** in `revealedToken`; only its bcrypt hash is stored. `scopes` defaults to `[\"transactions:submit\", \"transactions:read\"]`; scope names are not validated. Audit-logged (`apikey.create`).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Users & API keys" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "live": { "type": "boolean" } }, "required": [ "label" ] }, "example": { "label": "NetSuite production", "scopes": [ "peppol:validate", "peppol:submit", "transactions:read" ], "live": true } } } }, "responses": { "201": { "description": "Created. The token is returned only in this response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string" }, "apiKeyId": { "type": "string" }, "tenantId": { "type": "string" }, "label": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "createdBy": { "type": "string" }, "createdAt": { "type": "string" }, "revealedToken": { "type": "string" } } }, "example": { "_id": "671f4b…", "apiKeyId": "ak_1789562400000_x7k2p9", "tenantId": "tnt_7Q2X…", "label": "NetSuite production", "prefix": "azd_live_AbCdEf", "scopes": [ "peppol:validate", "peppol:submit", "transactions:read" ], "status": "active", "createdBy": "user_1789…_5e6f", "createdAt": "2026-10-01T07:45:00.000Z", "revealedToken": "azd_live_AbCdEf_…" } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/api-keys/{apiKeyId}/revoke": { "post": { "operationId": "postTenantApiKeysByApiKeyIdRevoke", "summary": "Revoke an API key", "description": "Sets the key to `revoked`; it is refused from the next request on. Idempotent — revoking a revoked key succeeds and keeps the original `revokedAt`. A key of another tenant answers 404. Audit-logged (`apikey.revoke`).\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Users & API keys" ], "parameters": [ { "name": "apiKeyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "The key is revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiKeyId": { "type": "string" }, "status": { "type": "string" }, "revokedAt": { "type": "string" } } }, "example": { "ok": true, "apiKeyId": "ak_1789562400000_x7k2p9", "status": "revoked", "revokedAt": "2026-10-24T10:00:00.000Z" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/audit-logs": { "get": { "operationId": "getTenantAuditLogs", "summary": "List the tenant's audit log", "description": "Paged audit rows of the tenant, newest first. Filters: `actor` (actor type), `outcome`, `action` (exact), `resourceType`, `from` / `to` and `q` (action, actor label or resource id). A `tenant_user` only sees rows whose resource id is one of their allowed companies or participants.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 } }, { "name": "actor", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "user", "api_key", "system", "super_admin" ] } }, { "name": "outcome", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "success", "denied", "failure" ] } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "resourceType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "tenant", "participant", "subsidiary", "location", "webhook", "user", "api_key", "transaction", "outbox_event" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}" } ] } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "One page of audit rows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "auditId": { "type": "string" }, "tenantId": { "type": "string" }, "actor": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" } } }, "action": { "type": "string" }, "resource": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } }, "outcome": { "type": "string" }, "createdAt": { "type": "string" } } } }, "page": { "type": "object", "properties": { "number": { "type": "integer" }, "size": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } } } }, "example": { "items": [ { "_id": "671f8f…", "auditId": "aud_1789562400000_k2j3l4", "tenantId": "tnt_7Q2X…", "actor": { "type": "user", "id": "user_1789…_5e6f", "label": "o***@example.com" }, "action": "apikey.create", "resource": { "type": "api_key", "id": "ak_1789562400000_x7k2p9" }, "outcome": "success", "createdAt": "2026-10-01T07:45:00.000Z" } ], "page": { "number": 1, "size": 25, "total": 1, "totalPages": 1 } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/participants": { "get": { "operationId": "getTenantParticipants", "summary": "List the tenant's Peppol participants", "description": "The tenant's Peppol identities (read-only; default first, then newest), each with its company (`subsidiary`: name, legal name, TRN, country, currency), a `displayName` and `canSend` — true when the participant is active, outbound-capable and has a C1 country code. A `tenant_user` only sees participants of allowed companies or allowed Peppol ids.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Company & participants" ], "responses": { "200": { "description": "The participants.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "participantId": { "type": "string" }, "tenantId": { "type": "string" }, "peppolId": { "type": "string" }, "scheme": { "type": "string" }, "value": { "type": "string" }, "direction": { "type": "string" }, "environment": { "type": "string" }, "allowedSenders": { "type": "array", "items": {} }, "endpointUrl": { "type": "string" }, "label": { "type": "string" }, "subsidiaryId": { "type": "string" }, "locationId": { "type": "string" }, "isDefault": { "type": "boolean" }, "status": { "type": "string" }, "smpPublishStatus": { "type": "string" }, "c1CountryCode": { "type": "string" }, "createdBy": { "type": "null" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "subsidiary": { "type": "object", "properties": { "subsidiaryId": { "type": "string" }, "name": { "type": "string" }, "legalName": { "type": "string" }, "country": { "type": "string" }, "taxRegistrationNumber": { "type": "string" }, "defaultCurrency": { "type": "string" } } }, "displayName": { "type": "string" }, "canSend": { "type": "boolean" } } } } } }, "example": { "items": [ { "_id": "671f6d…", "participantId": "pp_3a9c1e…", "tenantId": "tnt_7Q2X…", "peppolId": "0235:1004****59", "scheme": "0235", "value": "1004****59", "direction": "both", "environment": "production", "allowedSenders": [], "endpointUrl": "", "label": "Production TRN", "subsidiaryId": "sub_1789…_a1b2", "locationId": "", "isDefault": true, "status": "active", "smpPublishStatus": "published", "c1CountryCode": "AE", "createdBy": null, "createdAt": "2026-09-01T08:10:00.000Z", "updatedAt": "2026-09-03T10:00:00.000Z", "subsidiary": { "subsidiaryId": "sub_1789…_a1b2", "name": "Sample Trading", "legalName": "Sample Trading LLC", "country": "AE", "taxRegistrationNumber": "1004****59", "defaultCurrency": "AED" }, "displayName": "Sample Trading LLC", "canSend": true } ] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "post": { "operationId": "postTenantParticipants", "summary": "Register a Peppol participant (closed: EmaraTax only)", "description": "No longer creates participants. Taxpayers are onboarded only from EmaraTax: the FTA verifies the company and the onboarding flow creates its `0235:` participant (and publishes it in the SMP). This route answers 403 `PEPPOL_ID_EMARATAX_ONLY` for every body; it stays mounted so existing callers get a clear answer. List participants with `GET /api/tenant/participants`. Requires the `tenant_admin` role; a `tenant_user` gets 403.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Company & participants" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "peppolId": { "type": "string" }, "direction": { "type": "string" }, "environment": { "type": "string" }, "subsidiaryId": { "type": "string" } } }, "example": { "peppolId": "0235:1004****59", "direction": "both", "environment": "production", "subsidiaryId": "sub_1789…_a1b2" } } } }, "responses": { "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "description": "Participants are created only by EmaraTax onboarding.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" } } } } }, "example": { "error": { "code": "PEPPOL_ID_EMARATAX_ONLY" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/subsidiaries/{subsidiaryId}": { "patch": { "operationId": "patchTenantSubsidiariesBySubsidiaryId", "summary": "Update a company", "description": "Updates the given fields of one of the caller's companies (another tenant's id answers 404). `country` and `defaultCurrency` are upper-cased; `sellerProfile`, when present, replaces the stored profile as a whole; `isDefault: true` clears the previous default. A duplicate `code` answers 409 `SUBSIDIARY_CODE_TAKEN`. Audit-logged (`subsidiary.update`). Requires the `tenant_admin` role; a `tenant_user` gets 403.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Company & participants" ], "parameters": [ { "name": "subsidiaryId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "legalName": { "type": "string" }, "code": { "type": "string" }, "country": { "type": "string", "maxLength": 2, "minLength": 2 }, "taxRegistrationNumber": { "type": "string" }, "defaultCurrency": { "type": "string" }, "isDefault": { "type": "boolean" }, "sellerProfile": { "type": "object", "properties": { "legalRegistrationId": { "type": "string" }, "legalRegistrationType": { "type": "string", "enum": [ "TL", "EID", "PAS", "CD" ] }, "legalRegistrationAuthorityName": { "type": "string" }, "address": { "type": "object", "properties": { "streetName": { "type": "string" }, "cityName": { "type": "string" }, "countrySubentity": { "type": "string" }, "postalZone": { "type": "string" } } } } } } }, "example": { "legalName": "Sample Trading LLC", "sellerProfile": { "legalRegistrationId": "CN-12****7", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development", "address": { "streetName": "Sheikh Zayed Road", "cityName": "Dubai", "countrySubentity": "DXB", "postalZone": "00000" } } } } } }, "responses": { "200": { "description": "The updated company.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "subsidiary": { "type": "object", "properties": { "_id": { "type": "string" }, "subsidiaryId": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "legalName": { "type": "string" }, "code": { "type": "string" }, "country": { "type": "string" }, "taxRegistrationNumber": { "type": "string" }, "netsuiteSubsidiaryId": { "type": "string" }, "defaultCurrency": { "type": "string" }, "status": { "type": "string" }, "isDefault": { "type": "boolean" }, "sellerProfile": { "type": "object", "properties": { "legalRegistrationId": { "type": "string" }, "legalRegistrationType": { "type": "string" }, "legalRegistrationAuthorityName": { "type": "string" }, "address": { "type": "object", "properties": { "streetName": { "type": "string" }, "cityName": { "type": "string" }, "countrySubentity": { "type": "string" }, "postalZone": { "type": "string" } } } } }, "deletedAt": { "type": "null" }, "createdBy": { "type": "null" }, "updatedBy": { "type": "null" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } } } }, "example": { "ok": true, "subsidiary": { "_id": "671f2c…", "subsidiaryId": "sub_1789…_a1b2", "tenantId": "tnt_7Q2X…", "name": "Sample Trading", "legalName": "Sample Trading LLC", "code": "AE-HQ", "country": "AE", "taxRegistrationNumber": "1004****59", "netsuiteSubsidiaryId": "", "defaultCurrency": "AED", "status": "active", "isDefault": true, "sellerProfile": { "legalRegistrationId": "CN-12****7", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development", "address": { "streetName": "Sheikh Zayed Road", "cityName": "Dubai", "countrySubentity": "DXB", "postalZone": "00000" } }, "deletedAt": null, "createdBy": null, "updatedBy": null, "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-10-20T09:15:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "409": { "description": "The company code is already used (`SUBSIDIARY_CODE_TAKEN`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" } } } } }, "example": { "error": { "code": "SUBSIDIARY_CODE_TAKEN" } } } } }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/branding": { "get": { "operationId": "getTenantBranding", "summary": "Get the tenant's logo facts", "description": "Whether a company logo is set for the signed-in tenant, with its type, size and pixel dimensions — never the bytes. Open to every tenant role: the Tenant Console shows the logo to everyone. Pinned to the caller's tenant.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "responses": { "200": { "description": "The logo's facts, or `logo: null` when none is set.", "content": { "application/json": { "schema": { "type": "object", "properties": { "logo": { "type": "object", "properties": { "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "updatedAt": { "type": "string" } } } } }, "example": { "logo": { "contentType": "image/png", "sizeBytes": 18234, "width": 320, "height": 96, "updatedAt": "2026-10-28T09:12:00.000Z" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/branding/logo": { "get": { "operationId": "getTenantBrandingLogo", "summary": "Download the tenant's logo image", "description": "The logo bytes as `image/png` or `image/jpeg`, with `Cache-Control: private, max-age=300`; the Tenant Console appends `?v=` to bust it after a change. 404 when no logo is set.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "responses": { "200": { "description": "The image.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "put": { "operationId": "putTenantBrandingLogo", "summary": "Upload or replace the tenant's logo", "description": "Tenant administrators only, through `company.manage`. The body carries the file as base64 with its declared type. Rules: PNG or JPEG only — SVG is refused because it can carry scripts — at most 512 KB, between 16 and 4096 pixels on each side, and the bytes must be the type declared. Stored on the tenant document (`tenants.branding.logo`). Audited as `tenant.branding.logo.update`.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contentType": { "type": "string", "enum": [ "image/png", "image/jpeg" ] }, "dataBase64": { "type": "string", "minLength": 1, "maxLength": 720000 } }, "required": [ "contentType", "dataBase64" ], "additionalProperties": false }, "example": { "contentType": "image/png", "dataBase64": "iVBORw0KGgoAAAANSUhEUgAAAUAAAABg…" } } } }, "responses": { "200": { "description": "The stored logo's facts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "logo": { "type": "object", "properties": { "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "updatedAt": { "type": "string" } } } } }, "example": { "logo": { "contentType": "image/png", "sizeBytes": 18234, "width": 320, "height": 96, "updatedAt": "2026-10-28T09:12:00.000Z" } } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "delete": { "operationId": "deleteTenantBrandingLogo", "summary": "Remove the tenant's logo", "description": "Tenant administrators only. The Tenant Console falls back to the AZDAN mark. Audited as `tenant.branding.logo.delete`.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "responses": { "200": { "description": "Removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "logo": { "type": "null" } } }, "example": { "logo": null } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "404": { "$ref": "#/components/responses/ErrNotFound" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/onboarding/companies": { "get": { "operationId": "getTenantOnboardingCompanies", "summary": "Get company onboarding readiness", "description": "One entry per company with its seller profile, its participants and a `readinessState`: `live` (active production participant published in the SMP), `production_pending` (active production participant not yet published), `test_ready` (active test participant) or `draft`. A `tenant_user` only sees allowed companies and participants.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Company & participants" ], "responses": { "200": { "description": "The companies and their readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "subsidiaryId": { "type": "string" }, "name": { "type": "string" }, "legalName": { "type": "string" }, "code": { "type": "string" }, "country": { "type": "string" }, "taxRegistrationNumber": { "type": "string" }, "status": { "type": "string" }, "isDefault": { "type": "boolean" }, "sellerProfile": { "type": "object", "properties": { "legalRegistrationId": { "type": "string" }, "legalRegistrationType": { "type": "string" }, "legalRegistrationAuthorityName": { "type": "string" }, "address": { "type": "object", "properties": { "streetName": { "type": "string" }, "cityName": { "type": "string" }, "countrySubentity": { "type": "string" }, "postalZone": { "type": "string" } } } } }, "readinessState": { "type": "string" }, "peppolIds": { "type": "array", "items": { "type": "string" } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "participantId": { "type": "string" }, "peppolId": { "type": "string" }, "environment": { "type": "string" }, "direction": { "type": "string" }, "status": { "type": "string" }, "smpPublishStatus": { "type": "string" }, "isDefault": { "type": "boolean" } } } } } } } } }, "example": { "items": [ { "subsidiaryId": "sub_1789…_a1b2", "name": "Sample Trading", "legalName": "Sample Trading LLC", "code": "AE-HQ", "country": "AE", "taxRegistrationNumber": "1004****59", "status": "active", "isDefault": true, "sellerProfile": { "legalRegistrationId": "CN-12****7", "legalRegistrationType": "TL", "legalRegistrationAuthorityName": "Department of Economic Development", "address": { "streetName": "Sheikh Zayed Road", "cityName": "Dubai", "countrySubentity": "DXB", "postalZone": "00000" } }, "readinessState": "live", "peppolIds": [ "0235:1004****59" ], "participants": [ { "participantId": "pp_3a9c1e…", "peppolId": "0235:1004****59", "environment": "production", "direction": "both", "status": "active", "smpPublishStatus": "published", "isDefault": true } ] } ] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/transactions/submit": { "post": { "operationId": "postTenantTransactionsSubmit", "summary": "Legacy mock submit (sends nothing)", "description": "Legacy endpoint kept for an old portal page. It validates the body shape, rejects a `payloadBase64` longer than 8 MiB characters (400), and answers 202 with a generated `txn_` id and `bridge: \"mock\"`. Nothing is stored, validated as Peppol, or sent to AP Core, and the returned id cannot be looked up. Use `POST /api/tenant/invoices/send` instead.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documentType": { "type": "string" }, "receiver": { "type": "object", "properties": { "participantId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "participantId" ] }, "payloadBase64": { "type": "string", "minLength": 1 }, "correlationId": { "type": "string" } }, "required": [ "documentType", "receiver", "payloadBase64" ] }, "example": { "documentType": "invoice", "receiver": { "participantId": "0235:1002****03", "name": "Sample Buyer FZ-LLC" }, "payloadBase64": "PD94bWwgdmVyc2lvbj0iMS4wIj8+…", "correlationId": "erp-INV-2026-000123" } } } }, "responses": { "202": { "description": "Mock acknowledgement; nothing was sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionId": { "type": "string" }, "tenantId": { "type": "string" }, "status": { "type": "string" }, "documentType": { "type": "string" }, "bridge": { "type": "string" } } }, "example": { "transactionId": "txn_1789562400000", "tenantId": "tnt_7Q2X…", "status": "queued", "documentType": "invoice", "bridge": "mock" } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "deprecated": true, "x-azdan-access": "tenant" } }, "/api/tenant/plan": { "get": { "operationId": "getTenantPlan", "summary": "Get the tenant's plan and usage", "description": "The tenant's plan (name, limits — `null` = unlimited — and reference price), usage this calendar month in UAE time and any limit the usage is over. Actions beyond a limit are refused with 403 `PLAN_LIMIT_REACHED` (`details`: `limit`, `used`, `max`, `plan`). Plans are changed by AZDAN.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "responses": { "200": { "description": "Plan and usage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenantId": { "type": "string" }, "planCode": { "type": "string" }, "plan": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "highlights": { "type": "array", "items": {} }, "status": { "type": "string" }, "isDefault": { "type": "boolean" }, "sortOrder": { "type": "integer" }, "price": { "type": "object", "properties": { "monthly": { "type": "null" }, "annual": { "type": "null" }, "currency": { "type": "string" } } }, "limits": { "type": "object", "properties": { "documentsPerMonth": { "type": "integer" }, "users": { "type": "integer" }, "participants": { "type": "integer" }, "apiKeys": { "type": "integer" }, "webhooks": { "type": "integer" } } }, "updatedAt": { "type": "string" } } }, "usage": { "type": "object", "properties": { "documentsPerMonth": { "type": "integer" }, "users": { "type": "integer" }, "participants": { "type": "integer" }, "apiKeys": { "type": "integer" }, "webhooks": { "type": "integer" } } }, "overLimits": { "type": "array", "items": {} }, "period": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "timeZone": { "type": "string" } } } } }, "example": { "tenantId": "tnt_7Q2X…", "planCode": "starter", "plan": { "code": "starter", "name": "Starter", "description": "For a single business starting with e-invoicing.", "highlights": [], "status": "active", "isDefault": true, "sortOrder": 10, "price": { "monthly": null, "annual": null, "currency": "AED" }, "limits": { "documentsPerMonth": 500, "users": 3, "participants": 1, "apiKeys": 2, "webhooks": 2 }, "updatedAt": "2026-10-26T09:00:00.000Z" }, "usage": { "documentsPerMonth": 128, "users": 2, "participants": 1, "apiKeys": 1, "webhooks": 0 }, "overLimits": [], "period": { "from": "2026-09-30T20:00:00.000Z", "to": "2026-10-31T20:00:00.000Z", "timeZone": "Asia/Dubai" } } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/subscription": { "get": { "operationId": "getTenantSubscription", "summary": "Get the tenant's subscription and usage", "description": "The subscription the Current Plan badge and Plan & usage page show: pricing model (`legacy` plan catalogue — with the plan summary under `legacy` —, `free` or `annual`), status, EmaraTax accounts and package, the period's credit pool (`credits`: carried over + included + package, pooled across the account's companies; unused credits roll over on renewal) and its usage (inbound + outbound documents counted once each when successfully processed), remaining documents, excess beyond the quota, the end / renewal date, the billing snapshot (ex VAT, VAT, incl. VAT, AED), quota warnings (80 / 90 / 100 %) and expiry warnings (30 / 7 / 0 days), whether new documents are processed right now, and `connections`: how many companies may be connected through EmaraTax (the subscription's EmaraTax accounts; the Free plan allows one; `unlimited` for a legacy tenant), how many are, and what is left. Changes are made by AZDAN — ask for one with `POST /api/tenant/subscription/requests`.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "responses": { "200": { "description": "The subscription.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tenantId": { "type": "string" }, "tenantName": { "type": "string" }, "subscription": { "type": "object", "properties": { "pricingModel": { "type": "string" }, "status": { "type": "string" }, "catalogueVersion": { "type": "integer" }, "accounts": { "type": "integer" }, "seats": { "type": "integer" }, "packageCapacity": { "type": "integer" }, "package": { "type": "object", "properties": { "code": { "type": "string" }, "capacity": { "type": "integer" }, "annualFee": { "type": "integer" }, "name": { "type": "object", "properties": { "en": { "type": "string" }, "ar": { "type": "string" } } } } }, "customQuote": { "type": "null" }, "annualDocuments": { "type": "integer" }, "includedDocuments": { "type": "integer" }, "credits": { "type": "object", "properties": { "carried": { "type": "integer" }, "included": { "type": "integer" }, "package": { "type": "integer" }, "total": { "type": "integer" } } }, "pricing": { "type": "object", "properties": { "currency": { "type": "string" }, "accountFee": { "type": "integer" }, "packageFee": { "type": "integer" }, "subtotalExVat": { "type": "integer" }, "vatRate": { "type": "number" }, "vat": { "type": "number" }, "totalIncVat": { "type": "number" }, "monthlyEquivalentExVat": { "type": "number" }, "monthlyEquivalentIncVat": { "type": "number" } } }, "startsAt": { "type": "string" }, "endsAt": { "type": "string" }, "nextRenewalAt": { "type": "string" }, "activatedAt": { "type": "string" }, "cancelledAt": { "type": "null" }, "daysLeft": { "type": "integer" }, "allowQuotaExceedance": { "type": "boolean" }, "notes": { "type": "null" }, "updatedAt": { "type": "string" }, "updatedBy": { "type": "string" } } }, "planName": { "type": "string" }, "period": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "kind": { "type": "string" } } }, "usage": { "type": "object", "properties": { "periodKey": { "type": "string" }, "used": { "type": "integer" }, "pending": { "type": "integer" }, "excess": { "type": "integer" }, "quota": { "type": "integer" }, "remaining": { "type": "integer" }, "percent": { "type": "number" }, "notified": { "type": "array", "items": {} } } }, "breakdown": { "type": "object", "properties": { "inbound": { "type": "integer" }, "outbound": { "type": "integer" } } }, "warnings": { "type": "array", "items": {} }, "processingAllowed": { "type": "boolean" }, "legacy": { "type": "null" } } }, "example": { "tenantId": "tnt_7Q2X…", "tenantName": "Acme Trading", "subscription": { "pricingModel": "annual", "status": "active", "catalogueVersion": 2, "accounts": 2, "seats": 2, "packageCapacity": 600, "package": { "code": "docs-600", "capacity": 600, "annualFee": 200, "name": { "en": "600 additional documents a year", "ar": "600 مستند إضافي سنويًا" } }, "customQuote": null, "annualDocuments": 3000, "includedDocuments": 2400, "credits": { "carried": 0, "included": 2400, "package": 600, "total": 3000 }, "pricing": { "currency": "AED", "accountFee": 1896, "packageFee": 200, "subtotalExVat": 2096, "vatRate": 0.05, "vat": 104.8, "totalIncVat": 2200.8, "monthlyEquivalentExVat": 174.67, "monthlyEquivalentIncVat": 183.4 }, "startsAt": "2026-10-29T08:00:00.000Z", "endsAt": "2027-10-29T08:00:00.000Z", "nextRenewalAt": "2027-10-29T08:00:00.000Z", "activatedAt": "2026-10-29T08:00:00.000Z", "cancelledAt": null, "daysLeft": 365, "allowQuotaExceedance": false, "notes": null, "updatedAt": "2026-10-29T08:00:00.000Z", "updatedBy": "user_1…" }, "planName": "AZDAN E-Invoicing", "period": { "from": "2026-10-29T08:00:00.000Z", "to": "2027-10-29T08:00:00.000Z", "kind": "year" }, "usage": { "periodKey": "sub:2026-10-29T08:00:00.000Z", "used": 128, "pending": 2, "excess": 0, "quota": 3000, "remaining": 2870, "percent": 4.3, "notified": [] }, "breakdown": { "inbound": 40, "outbound": 88 }, "warnings": [], "processingAllowed": true, "legacy": null } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/subscription/pricing": { "get": { "operationId": "getTenantSubscriptionPricing", "summary": "Get the AZDAN E-Invoicing price list", "description": "The active pricing catalogue (`version`, `items` with bilingual names: Free plan, EmaraTax account, onboarding, the 32 document packages, custom quote) and the constants: account price (AED 948 a year, 1,200 credits included), the packages, the custom-quote threshold, the VAT rate and the free allowance (120 documents a year). Ex VAT; billing is annual; monthly figures are informational.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "responses": { "200": { "description": "The price list.", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "vatRate": { "type": "number" }, "account": { "type": "object", "properties": { "annualFee": { "type": "integer" }, "monthlyEquivalent": { "type": "integer" }, "annualDocuments": { "type": "integer" }, "maxAccounts": { "type": "integer" } } }, "packages": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "capacity": { "type": "integer" }, "annualFee": { "type": "integer" }, "monthlyEquivalent": { "type": "number" } } } }, "customQuoteAbove": { "type": "integer" }, "free": { "type": "object", "properties": { "documents": { "type": "integer" }, "annualFee": { "type": "integer" } } }, "onboardingFee": { "type": "integer" }, "version": { "type": "integer" }, "items": { "type": "array", "items": {} } } }, "example": { "currency": "AED", "vatRate": 0.05, "account": { "annualFee": 948, "monthlyEquivalent": 79, "annualDocuments": 1200, "maxAccounts": 1000 }, "packages": [ { "code": "docs-600", "capacity": 600, "annualFee": 200, "monthlyEquivalent": 16.67 } ], "customQuoteAbove": 238800, "free": { "documents": 120, "annualFee": 0 }, "onboardingFee": 0, "version": 2, "items": [] } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } }, "/api/tenant/subscription/requests": { "get": { "operationId": "getTenantSubscriptionRequests", "summary": "List the tenant's subscription requests", "description": "Every request this account made for a subscription change (newest first) with its status (`pending`, `under_review`, `approved`, `completed`, `rejected`), what was asked for (`requested`: the target subscription), the price list's estimate, the comment, AZDAN's decision and reason, and the history; `open` says whether one is still being handled.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "responses": { "200": { "description": "The requests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "type": "object", "properties": { "requestId": { "type": "string" }, "tenantId": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "requested": { "type": "object", "properties": { "model": { "type": "string" }, "accounts": { "type": "integer" }, "additionalAccounts": { "type": "integer" }, "packageCapacity": { "type": "integer" }, "catalogueKey": { "type": "null" }, "catalogueVersion": { "type": "integer" } } }, "estimate": { "type": "object", "properties": { "model": { "type": "string" }, "accounts": { "type": "integer" }, "packageCapacity": { "type": "integer" }, "annualDocuments": { "type": "integer" }, "subtotalExVat": { "type": "integer" }, "vat": { "type": "number" }, "totalIncVat": { "type": "number" }, "currency": { "type": "string" } } }, "comment": { "type": "string" }, "snapshot": { "type": "object", "properties": { "pricingModel": { "type": "string" }, "accounts": { "type": "integer" }, "packageCapacity": { "type": "integer" }, "usage": { "type": "object", "properties": { "used": { "type": "integer" }, "pending": { "type": "integer" }, "quota": { "type": "integer" }, "percent": { "type": "integer" } } }, "connections": { "type": "object", "properties": { "connected": { "type": "integer" }, "limit": { "type": "integer" } } } } }, "requestedBy": { "type": "object", "properties": { "label": { "type": "string" } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "review": { "type": "null" }, "decision": { "type": "null" }, "applied": { "type": "null" }, "appliedAt": { "type": "null" }, "applyError": { "type": "null" }, "history": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string" }, "status": { "type": "string" }, "by": { "type": "string" }, "note": { "type": "null" } } } } } } }, "open": { "type": "boolean" } } }, "example": { "requests": [ { "requestId": "sreq_1761732000000_a1b2c3d4", "tenantId": "tnt_7Q2X…", "type": "accounts", "status": "pending", "requested": { "model": "annual", "accounts": 3, "additionalAccounts": 1, "packageCapacity": 600, "catalogueKey": null, "catalogueVersion": 2 }, "estimate": { "model": "annual", "accounts": 3, "packageCapacity": 600, "annualDocuments": 4200, "subtotalExVat": 3044, "vat": 152.2, "totalIncVat": 3196.2, "currency": "AED" }, "comment": "A new subsidiary", "snapshot": { "pricingModel": "annual", "accounts": 2, "packageCapacity": 600, "usage": { "used": 120, "pending": 0, "quota": 3000, "percent": 4 }, "connections": { "connected": 2, "limit": 2 } }, "requestedBy": { "label": "finance@acme.ae" }, "createdAt": "2026-10-29T10:00:00.000Z", "updatedAt": "2026-10-29T10:00:00.000Z", "review": null, "decision": null, "applied": null, "appliedAt": null, "applyError": null, "history": [ { "at": "2026-10-29T10:00:00.000Z", "status": "pending", "by": "finance@acme.ae", "note": null } ] } ], "open": true } } } }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" }, "post": { "operationId": "postTenantSubscriptionRequests", "summary": "Ask AZDAN for a subscription change", "description": "Admin and Finance roles. `type`: `upgrade` (to an annual subscription of `accounts` EmaraTax accounts and an optional `packageCapacity`), `change` (another annual size, or `model: free` for the Free plan), `accounts` (`additionalAccounts` more EmaraTax accounts — more companies can then be connected), `package` (`packageCapacity`: one of the 32 packages of the price list). An optional `comment` (≤ 1,000 characters). The request is normalised to the target subscription and priced from the price list for information; nothing changes and nothing is charged until an AZDAN administrator approves and applies it. One open request per account at a time (409). The account's administrators are emailed when it is received and at each status change.\n\n**Access:** Tenant session: `tenant_admin` or `tenant_user` of the tenant. Data is always scoped to that tenant.", "tags": [ "Settings & integrations" ], "parameters": [ { "$ref": "#/components/parameters/CsrfToken" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "upgrade", "change", "accounts", "package" ] }, "model": { "type": "string", "enum": [ "free", "annual" ] }, "accounts": { "type": "integer", "minimum": 1, "maximum": 1000 }, "additionalAccounts": { "type": "integer", "minimum": 1, "maximum": 1000 }, "packageCapacity": { "type": "integer", "minimum": 0 }, "comment": { "type": "string", "maxLength": 1000 } }, "required": [ "type" ], "additionalProperties": false }, "example": { "type": "accounts", "additionalAccounts": 1, "comment": "A new subsidiary joins in November" } } } }, "responses": { "201": { "description": "The request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" }, "tenantId": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "requested": { "type": "object", "properties": { "model": { "type": "string" }, "accounts": { "type": "integer" }, "additionalAccounts": { "type": "integer" }, "packageCapacity": { "type": "integer" }, "catalogueKey": { "type": "null" }, "catalogueVersion": { "type": "integer" } } }, "estimate": { "type": "object", "properties": { "model": { "type": "string" }, "accounts": { "type": "integer" }, "packageCapacity": { "type": "integer" }, "annualDocuments": { "type": "integer" }, "subtotalExVat": { "type": "integer" }, "vat": { "type": "number" }, "totalIncVat": { "type": "number" }, "currency": { "type": "string" } } }, "comment": { "type": "string" }, "createdAt": { "type": "string" }, "history": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string" }, "status": { "type": "string" }, "by": { "type": "string" }, "note": { "type": "null" } } } } } }, "example": { "requestId": "sreq_1761732000000_a1b2c3d4", "tenantId": "tnt_7Q2X…", "type": "accounts", "status": "pending", "requested": { "model": "annual", "accounts": 3, "additionalAccounts": 1, "packageCapacity": 600, "catalogueKey": null, "catalogueVersion": 2 }, "estimate": { "model": "annual", "accounts": 3, "packageCapacity": 600, "annualDocuments": 4200, "subtotalExVat": 3044, "vat": 152.2, "totalIncVat": 3196.2, "currency": "AED" }, "comment": "A new subsidiary joins in November", "createdAt": "2026-10-29T10:00:00.000Z", "history": [ { "at": "2026-10-29T10:00:00.000Z", "status": "pending", "by": "finance@acme.ae", "note": null } ] } } } }, "400": { "$ref": "#/components/responses/ErrBadRequest" }, "401": { "$ref": "#/components/responses/ErrUnauthorized" }, "403": { "$ref": "#/components/responses/ErrForbidden" }, "409": { "$ref": "#/components/responses/ErrConflict" }, "500": { "$ref": "#/components/responses/ErrInternal" } }, "security": [ { "BearerJWT": [] }, { "SessionCookie": [] } ], "x-azdan-access": "tenant" } } }, "components": { "parameters": { "CsrfToken": { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required with cookie sessions on unsafe methods: the value of the `azdan_csrf` cookie. Not needed with `Authorization: Bearer`.", "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Send Idempotency-Key as an HTTP header on submit. The key identifies ONE logical submission, scoped to the tenant: the same key always returns the original transaction (idempotent: true) and never sends twice, so retry a timeout or a 5xx with the SAME key and use a new key for a new document. 1 to 120 characters — a longer key is refused with HTTP 400 IDEMPOTENCY_KEY_INVALID before anything is stored, and the same limit applies to the legacy body field idempotencyKey and to the by-idempotency lookup. The header is authoritative; if the legacy body field is also sent the two must be equal (IDEMPOTENCY_KEY_CONFLICT).", "example": "invoice-INV-2026-000123" }, "TransactionIdPath": { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Platform transaction id (`txn_*`) or AP transaction id.", "example": "txn_1715690640123_a1b2c3d4" }, "CursorLimit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 }, "description": "Maximum items to return (cursor mode)." }, "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor from a previous response's `nextCursor`." }, "Sort": { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "createdAt:desc", "createdAt:asc", "updatedAt:desc" ], "default": "createdAt:desc" }, "description": "Sort order for cursor pagination." }, "Page": { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number (page mode only)." }, "PageSize": { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 25 }, "description": "Items per page (page mode only)." }, "FilterDirection": { "name": "direction", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Direction" } }, "FilterStatus": { "name": "status", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/TransactionStatus" } }, "FilterEnvironment": { "name": "environment", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Environment" } }, "FilterDocumentType": { "name": "documentType", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DocumentType" } }, "FilterSenderPeppolId": { "name": "senderPeppolId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "0235:1000000001" }, "FilterReceiverPeppolId": { "name": "receiverPeppolId", "in": "query", "required": false, "schema": { "type": "string" }, "example": "0235:1000000002" }, "FilterPeppolParticipantId": { "name": "peppolParticipantId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Match transactions where sender OR receiver matches." }, "FilterSubsidiaryId": { "name": "subsidiaryId", "in": "query", "required": false, "schema": { "type": "string" } }, "FilterCorrelationId": { "name": "correlationId", "in": "query", "required": false, "schema": { "type": "string" } }, "FilterAs4MessageId": { "name": "as4MessageId", "in": "query", "required": false, "schema": { "type": "string" } }, "FilterApCoreMessageId": { "name": "apCoreMessageId", "in": "query", "required": false, "schema": { "type": "string" } }, "FilterSbdhInstanceId": { "name": "sbdhInstanceId", "in": "query", "required": false, "schema": { "type": "string" } }, "FilterIdempotencyKey": { "name": "idempotencyKey", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 120 } }, "FilterDateFrom": { "name": "dateFrom", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only transactions created on or after this date." }, "FilterDateTo": { "name": "dateTo", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only transactions created on or before this date." }, "FilterMessageId": { "name": "messageId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Alias for apCoreMessageId filter." }, "FilterSearch": { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search across transactionId, correlationId, message IDs, and participant IDs." }, "IncludeParam": { "name": "include", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "storage" ] }, "description": "Opt-in to include additional data in list items.\n- `storage`: Attach a lightweight storage summary (driver, fileType, sizeBytes) to each item.\n No S3 keys or filesystem paths are exposed.\n" } }, "schemas": { "PlatformError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable code, e.g. VALIDATION, NOT_FOUND, FORBIDDEN, or a domain code." }, "message": { "type": "string", "description": "Human-readable message; safe to show." }, "details": { "description": "Optional structured context for the code." }, "issues": { "type": "array", "description": "Present on VALIDATION errors: the zod issues (path, message, code).", "items": { "type": "object", "properties": { "path": { "type": "array", "items": {} }, "message": { "type": "string" }, "code": { "type": "string" } } } } } } } }, "Direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "TransactionStatus": { "type": "string", "enum": [ "queued", "sending", "delivered", "failed", "received", "quarantined" ], "x-azdan-notes": "queued → sending → delivered (happy path)\nqueued → sending → failed (delivery error)\nreceived (inbound from network)\nquarantined (inbound held for review)\n" }, "Environment": { "type": "string", "enum": [ "test", "production" ], "description": "The Peppol network a document is routed to. Set per request (environment, default \"test\"), stored on the transaction and echoed in every webhook payload. The API key prefix does not influence it; the sender participant must be registered in the environment named." }, "SubmittableDocumentType": { "type": "string", "enum": [ "invoice", "creditNote" ], "description": "Document types accepted by validate and submit endpoints.\n- `invoice` — AE PINT Invoice\n- `creditNote` — AE PINT Credit Note\n" }, "DocumentType": { "type": "string", "enum": [ "invoice", "creditNote", "tdd" ], "description": "All Peppol document types that can appear in transaction responses and list filters.\n- `invoice` and `creditNote` are submittable via the API.\n- `tdd` (UAE Tax Data Document) is **read-only**: Tax Data Documents are generated automatically by AZDAN. Do not submit a TDD. Use the invoice transaction's TDD endpoint to inspect the generated TDD status and download it when available. Inspect it with GET /api/integrations/peppol/transactions/{transactionId}/tdd. Submitting `tdd` via validate or submit is rejected with HTTP 400 (invalid enum value).\n\nUse `SubmittableDocumentType` for request schemas; use `DocumentType` for response/filter schemas." }, "WebhookEventType": { "type": "string", "enum": [ "transaction.submitted", "ap.outbound.created", "ap.outbound.delivered", "ap.outbound.failed", "ap.inbound.received", "ap.mls.updated", "transaction.tdd_generated", "mls.sent", "mls.received", "mls.accepted", "mls.rejected", "tdd.reported", "transaction.status_changed", "document.validated", "document.rejected", "webhook.test" ], "x-azdan-notes": "Legacy (v1) names, as stored and as a v1 delivery's `type`:\ntransaction.submitted: Emitted immediately when POST /invoices succeeds (v2 name document.submitted).\nap.outbound.created: AP Core created the outbound row (v2 name document.sent).\nap.outbound.delivered: AS4 delivery confirmed (v2 name document.delivered).\nap.outbound.failed: Delivery failed permanently (v2 name document.failed).\nap.inbound.received: Inbound document received from network (v2 name document.received).\nap.mls.updated: Message Level Status receipt update (v2 name mls.updated).\ntransaction.tdd_generated: A UAE Tax Data Document was generated for a transaction (v2 name tdd.generated).\nmls.sent: This AP sent an MLS ApplicationResponse (linked to the originating transaction where known).\nmls.received: An MLS was received from a peer AP for one of the tenant's outbound transactions.\nTopics introduced with payload v2 (one name only):\nmls.accepted: The receiver's access point accepted or acknowledged the document (MLS AP / AB).\nmls.rejected: The receiver's access point rejected the document (MLS RE), with the reason.\ntdd.reported: The FTA's access point answered a Tax Data Document — outcome accepted or rejected, with the reason.\ntransaction.status_changed: The platform transaction moved to another status (previous and new status in the payload).\ndocument.validated: A document submitted through this API passed validation and was recorded.\ndocument.rejected: A document submitted through this API failed validation and was not sent (validation issues in the payload; no transaction).\nwebhook.test: A test event sent from the console.\n" }, "InputType": { "type": "string", "enum": [ "json", "xml" ] }, "ParticipantRef": { "type": "object", "properties": { "participantId": { "type": "string", "description": "Peppol participant ID (scheme:id format)", "example": "0235:1000000001" }, "name": { "type": "string", "nullable": true, "example": "Acme Trading LLC" } } }, "DocumentLink": { "type": "object", "required": [ "available", "fileName", "contentType", "downloadUrl" ], "description": "A single document reference inside the unified `documents` object. When\n`available` is false the file has not been generated/indexed yet:\n`fileName` and `downloadUrl` are null and consumers must treat it as\nnot-yet-present.\n", "properties": { "available": { "type": "boolean", "description": "Whether the file exists and can be downloaded." }, "fileName": { "type": "string", "nullable": true, "example": "INV-10001.xml" }, "contentType": { "type": "string", "description": "Expected MIME type (present even when unavailable).", "example": "application/xml" }, "downloadUrl": { "type": "string", "nullable": true, "description": "Authenticated Platform API download URL — NEVER a raw object-storage\n(OCI/S3) URL. Relative in API/portal responses; absolute in webhook\npayloads when `PUBLIC_API_BASE_URL` is configured. May resolve to a\nshort-lived signed URL, so do not cache it.\n", "example": "/api/integrations/peppol/transactions/txn_1715690640123_a1b2c3d4/files/invoice-xml" }, "reason": { "type": "string", "nullable": true, "enum": [ "metadata_only", "not_generated", "not_in_object_storage", "not_received", "not_stored", "not_stored_for_outbound", "transaction_not_found", null ], "description": "Present only when available is false: why the document is absent. documents..available on the transaction detail is computed from what is actually stored, and the download route resolves the same rows — the two never disagree. An unavailable entry carries reason: not_generated (PDF, TDD), metadata_only (MLS known from the access point without a stored file), not_received (no MLS), not_stored_for_outbound (an outbound submission is payload-only, the SBDH exists only inside the AS4 message) or not_stored. Optional documents answer 404 with the same reason in error.details; that is an expected state, not a failure. Privileged routes (raw payload, TDD signed download) answer 403 without the peppol:payload:read scope." } } }, "TddMetadata": { "type": "object", "properties": { "fileId": { "type": "string" }, "transactionId": { "type": "string", "description": "The invoice / credit note transaction the TDD reports on." }, "parentTransactionId": { "type": "string" }, "apTddTransactionId": { "type": "string", "description": "Access-point transaction id of the TDD transport itself." }, "status": { "type": "string", "nullable": true, "description": "Delivery status of the TDD transport (pending, sending, sent, failed, permanently_failed, …)." }, "documentTypeId": { "type": "string", "nullable": true }, "processId": { "type": "string", "nullable": true }, "generatedAt": { "type": "string", "format": "date-time", "nullable": true }, "sha256": { "type": "string" }, "sizeBytes": { "type": "integer" }, "contentType": { "type": "string" }, "source": { "type": "string", "example": "ap_core_generated_tdd" }, "sbdhInstanceId": { "type": "string", "nullable": true }, "apCoreMessageId": { "type": "string", "nullable": true }, "tddDownloadUrl": { "type": "string", "description": "Platform API route for the signed download (peppol:payload:read)." } }, "description": "Tax Data Documents are generated automatically by AZDAN. Do not submit a TDD. Use the invoice transaction's TDD endpoint to inspect the generated TDD status and download it when available." }, "TransactionDocuments": { "type": "object", "description": "documents..available on the transaction detail is computed from what is actually stored, and the download route resolves the same rows — the two never disagree. An unavailable entry carries reason: not_generated (PDF, TDD), metadata_only (MLS known from the access point without a stored file), not_received (no MLS), not_stored_for_outbound (an outbound submission is payload-only, the SBDH exists only inside the AS4 message) or not_stored. Optional documents answer 404 with the same reason in error.details; that is an expected state, not a failure. Privileged routes (raw payload, TDD signed download) answer 403 without the peppol:payload:read scope.", "required": [ "invoiceXml", "invoicePdf", "sbdXml", "tddXml", "mlsXml" ], "properties": { "invoiceXml": { "$ref": "#/components/schemas/DocumentLink" }, "invoicePdf": { "$ref": "#/components/schemas/DocumentLink" }, "sbdXml": { "$ref": "#/components/schemas/DocumentLink" }, "tddXml": { "$ref": "#/components/schemas/DocumentLink" }, "mlsXml": { "$ref": "#/components/schemas/DocumentLink" }, "payloadXml": { "type": "object", "description": "The stored business payload, served as a short-lived signed object-storage URL (303). Same bytes as Invoice XML; a different route with a privileged scope. Integration surface only.", "properties": { "available": { "type": "boolean" }, "privileged": { "type": "boolean", "enum": [ true ] }, "requiredScope": { "type": "string", "enum": [ "peppol:payload:read" ] }, "contentType": { "type": "string" }, "downloadUrl": { "type": "string", "nullable": true }, "reason": { "type": "string", "nullable": true } } } } }, "Transaction": { "type": "object", "properties": { "transactionId": { "type": "string", "example": "txn_1715690640123_a1b2c3d4" }, "direction": { "$ref": "#/components/schemas/Direction" }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "documentType": { "type": "string", "nullable": true }, "documentTypeId": { "type": "string", "nullable": true, "description": "Full Peppol document type URN." }, "processId": { "type": "string", "nullable": true, "example": "urn:peppol:bis:billing" }, "sender": { "$ref": "#/components/schemas/ParticipantRef" }, "receiver": { "$ref": "#/components/schemas/ParticipantRef" }, "correlationId": { "type": "string", "nullable": true }, "apCoreMessageId": { "type": "string", "nullable": true, "description": "AP Core / AS4 message ID." }, "as4MessageId": { "type": "string", "nullable": true, "description": "Alias of apCoreMessageId for convenience." }, "sbdhInstanceId": { "type": "string", "nullable": true }, "environment": { "$ref": "#/components/schemas/Environment" }, "sizeBytes": { "type": "integer", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "failedAt": { "type": "string", "format": "date-time", "nullable": true }, "failureReason": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true }, "documents": { "$ref": "#/components/schemas/TransactionDocuments" } } }, "CursorPagination": { "type": "object", "required": [ "mode", "limit", "hasNext" ], "properties": { "mode": { "type": "string", "const": "cursor" }, "limit": { "type": "integer" }, "nextCursor": { "type": "string", "nullable": true, "description": "Opaque token for the next page. Pass as `cursor` param." }, "prevCursor": { "type": "string", "nullable": true, "description": "Reserved for future bidirectional cursors." }, "hasNext": { "type": "boolean" } } }, "PagePagination": { "type": "object", "required": [ "page", "pageSize", "total", "totalPages", "hasMore" ], "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "hasMore": { "type": "boolean" } } }, "CursorListResponse": { "type": "object", "required": [ "items", "pagination" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "pagination": { "$ref": "#/components/schemas/CursorPagination" } } }, "PageListResponse": { "type": "object", "required": [ "transactions", "pagination" ], "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "pagination": { "$ref": "#/components/schemas/PagePagination" } } }, "WebhookEvent": { "type": "object", "properties": { "eventId": { "type": "string", "example": "evt_ap_a1b2c3d4e5f6g7h8" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "deliveryStatus": { "type": "string", "enum": [ "pending", "in_flight", "delivered", "failed", "dead" ] }, "payload": { "type": "object", "description": "Event-specific payload. All webhook payloads include the additive\n`documents` object when document lookup succeeds. For\n`transaction.tdd_generated`, the legacy `tddDownloadUrl` field is\nretained and `documents.tddXml` points at the same TDD through the\nunified secure document-download contract.\n", "properties": { "event": { "type": "string" }, "transactionId": { "type": "string" }, "status": { "type": "string" }, "direction": { "type": "string" }, "environment": { "type": "string" }, "sender": { "type": "string", "description": "Sender Peppol ID." }, "receiver": { "type": "string", "description": "Receiver Peppol ID." }, "documentType": { "type": "string" }, "processId": { "type": "string" }, "correlationId": { "type": "string" }, "apMessageId": { "type": "string" }, "sbdhInstanceId": { "type": "string" }, "tddDownloadUrl": { "type": "string", "nullable": true, "description": "Legacy TDD download URL retained for backward compatibility on `transaction.tdd_generated`.", "example": "/api/integrations/peppol/transactions/txn_1715690640123_a1b2c3d4/tdd/download" }, "documents": { "$ref": "#/components/schemas/TransactionDocuments" } } }, "createdAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": "string", "format": "date-time", "nullable": true }, "attempts": { "type": "integer" }, "lastError": { "type": "string", "nullable": true } } }, "EventsResponse": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "ApEnrichment": { "type": "object", "description": "AP Core link status. If `linked: true`, additional AP metadata is available.\nIf `linkAmbiguous: true`, multiple AP records match and the system cannot auto-link.\n", "required": [ "linked" ], "properties": { "linked": { "type": "boolean", "description": "Whether this transaction is linked to an AP Core record." }, "linkAmbiguous": { "type": "boolean", "description": "True if multiple AP candidates exist (no auto-link)." }, "candidateCount": { "type": "integer", "description": "Number of ambiguous AP candidates (only when linkAmbiguous)." }, "direction": { "$ref": "#/components/schemas/Direction" }, "apTransactionId": { "type": "string", "description": "AP Core's internal transaction ID." }, "status": { "type": "string", "description": "AP Core status (delivered, permanently_failed, sending, etc.)" }, "as4MessageId": { "type": "string", "nullable": true, "description": "AS4 transport message ID." }, "sbdhInstanceId": { "type": "string", "nullable": true }, "messageId": { "type": "string", "nullable": true, "description": "Same as as4MessageId (legacy alias)." }, "documentType": { "type": "string", "nullable": true }, "processId": { "type": "string", "nullable": true }, "sender": { "type": "string", "nullable": true, "description": "Normalised sender participant ID (without URI prefix)." }, "receiver": { "type": "string", "nullable": true, "description": "Normalised receiver participant ID (without URI prefix)." }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "errorDetails": { "type": "string", "nullable": true, "description": "AP error description (when status is permanently_failed)." }, "mlsStatus": { "type": "string", "nullable": true, "enum": [ "pending", "received_ap", "received_ab", "received_re", "not_applicable", null ], "description": "MLS values are lower-case, exactly as stored. ap.mlsStatus / ap.mlsReceivedAt / ap.mlsId / ap.mlsType / ap.mlsErrorCode / ap.mlsErrorMessage are metadata on the enriched detail; documents.mlsXml is available only when an MLS XML file is actually stored — for outbound documents it is normally not. Outbound only.", "example": "received_ap" }, "mlsReceivedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the MLS was received. Outbound only." }, "mlsId": { "type": "string", "nullable": true, "description": "Identifier of the MLS document. Outbound only." }, "mlsType": { "type": "string", "nullable": true, "description": "MLS document type recorded by the access point (either direction)." }, "mlsErrorCode": { "type": "string", "nullable": true, "description": "Error code carried by a negative MLS (received_re). Outbound only." }, "mlsErrorMessage": { "type": "string", "nullable": true, "description": "Error message carried by a negative MLS (received_re). Outbound only." }, "isTdd": { "type": "boolean", "description": "True only when THIS access-point row is itself a UAE Tax Data Document\ntransport. For an invoice or credit note it is always false — it does not\nsay whether a TDD was generated for the document (use GET\n…/transactions/{transactionId}/tdd for that).\n" }, "tddStatus": { "type": "string", "nullable": true, "description": "Status of this row when it is itself a TDD transport; always null for an\ninvoice or credit note. The generated TDD's delivery status is tdd.status\non GET …/transactions/{transactionId}/tdd.\n" } } }, "StorageInfo": { "type": "object", "nullable": true, "description": "Primary file storage metadata. The `s3Key` field is included in\nauthenticated detail responses but must not be logged or displayed\nin end-user UIs. Use the `/transactions/{id}/xml` endpoint\nto obtain a short-lived presigned download URL instead.\n", "properties": { "driver": { "type": "string", "enum": [ "s3", "local" ] }, "s3Key": { "type": "string", "nullable": true, "description": "S3 object key (detail view only, not in list storage summary).\n**Do not expose to end-users or store in client-side logs.**\nUse the `/transactions/{id}/xml` endpoint for downloads.\n", "x-internal": true }, "contentType": { "type": "string", "example": "application/xml" }, "fileType": { "type": "string", "enum": [ "payload", "sbdh", "mlr", "mdn", "envelope", "attachment", "receipt" ] }, "sizeBytes": { "type": "integer" }, "cleanupStatus": { "type": "string", "enum": [ "clean", "pending_cleanup" ], "description": "Whether a legacy local path still exists alongside S3." } } }, "FileInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "Original filename or generated name." }, "contentType": { "type": "string", "example": "application/xml" }, "sizeBytes": { "type": "integer" }, "storage": { "type": "string", "enum": [ "s3", "local" ] }, "s3Key": { "type": "string", "nullable": true, "description": "S3 object key (null for local-only files)." } } }, "PlatformMeta": { "type": "object", "description": "Platform-specific metadata for the transaction.", "properties": { "transactionId": { "type": "string" }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "correlationId": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true }, "validation": { "type": "object", "properties": { "engine": { "type": "string", "nullable": true } } }, "webhookSummary": { "type": "object", "nullable": true, "properties": { "totalEvents": { "type": "integer" }, "lastEventType": { "type": "string", "nullable": true }, "lastEventStatus": { "type": "string", "nullable": true }, "lastEventAt": { "type": "string", "format": "date-time", "nullable": true } } } } }, "TransactionLinks": { "type": "object", "description": "HATEOAS links to related resources.", "properties": { "self": { "type": "string" }, "events": { "type": "string" }, "xml": { "type": "string" } } }, "EnrichedTransactionDetail": { "type": "object", "required": [ "transaction", "platform", "ap", "storage", "files", "documents", "links" ], "properties": { "transaction": { "$ref": "#/components/schemas/Transaction" }, "platform": { "$ref": "#/components/schemas/PlatformMeta" }, "ap": { "$ref": "#/components/schemas/ApEnrichment" }, "storage": { "$ref": "#/components/schemas/StorageInfo" }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/FileInfo" } }, "documents": { "$ref": "#/components/schemas/TransactionDocuments" }, "links": { "$ref": "#/components/schemas/TransactionLinks" } } }, "ValidateRequest": { "type": "object", "required": [ "inputType", "environment", "documentType", "senderPeppolId", "receiverPeppolId" ], "properties": { "inputType": { "$ref": "#/components/schemas/InputType" }, "environment": { "$ref": "#/components/schemas/Environment" }, "documentType": { "$ref": "#/components/schemas/SubmittableDocumentType" }, "senderPeppolId": { "type": "string", "description": "Sender Peppol ID in scheme:id format.", "example": "0235:1000000001" }, "receiverPeppolId": { "type": "string", "description": "Receiver Peppol ID in scheme:id format.", "example": "0235:1000000002" }, "payload": { "type": "object", "description": "Invoice/credit note data (JSON mode only)." }, "xml": { "type": "string", "description": "Complete UBL XML document (XML mode only)." } } }, "SubmitRequest": { "type": "object", "required": [ "inputType", "environment", "documentType", "senderPeppolId", "receiverPeppolId" ], "properties": { "inputType": { "$ref": "#/components/schemas/InputType" }, "environment": { "$ref": "#/components/schemas/Environment" }, "documentType": { "$ref": "#/components/schemas/SubmittableDocumentType" }, "senderPeppolId": { "type": "string", "example": "0235:1000000001" }, "receiverPeppolId": { "type": "string", "example": "0235:1000000002" }, "idempotencyKey": { "type": "string", "minLength": 1, "deprecated": true, "maxLength": 120, "description": "Deprecated legacy alternative to the Idempotency-Key header. Prefer the HTTP header. If both are sent they must have the same value or the API returns IDEMPOTENCY_KEY_CONFLICT. Same 1 to 120 character limit as the header (IDEMPOTENCY_KEY_INVALID)." }, "payload": { "type": "object", "description": "Invoice/credit note data (JSON mode only)." }, "xml": { "type": "string", "description": "Complete UBL XML document (XML mode only)." } } }, "ValidateResponse": { "type": "object", "properties": { "valid": { "type": "boolean" }, "documentTypeId": { "type": "string" }, "processId": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "object" } }, "phormSkipped": { "type": "boolean", "description": "True if only local structural checks ran (Phorm unavailable)." }, "normalized": { "type": "object", "description": "Normalized sender/receiver and document metadata." } } }, "SubmitResponse": { "type": "object", "properties": { "transactionId": { "type": "string" }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "valid": { "type": "boolean" }, "documentTypeId": { "type": "string" }, "processId": { "type": "string" }, "correlationId": { "type": "string" }, "as4MessageId": { "type": "string", "nullable": true }, "sbdhInstanceId": { "type": "string", "nullable": true }, "idempotent": { "type": "boolean", "description": "True if this is a replay of a previous submission with the same idempotency key." }, "warnings": { "type": "array", "items": { "type": "object" } }, "validatorPhormSkipped": { "type": "boolean" }, "documents": { "$ref": "#/components/schemas/TransactionDocuments" }, "message": { "type": "string" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code. See the ErrorCatalog schema for every value.", "example": "PINT_VALIDATION_FAILED" }, "message": { "type": "string", "description": "Human-readable error description." }, "details": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "string" } } } } } } } } }, "responses": { "ErrBadRequest": { "description": "The request is invalid. `VALIDATION` errors list each failed field in `issues`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformError" }, "example": { "error": { "code": "VALIDATION", "message": "Invalid request", "issues": [ { "code": "invalid_type", "path": [ "name" ], "message": "Required" } ] } } } } }, "ErrUnauthorized": { "description": "Missing, invalid or expired credentials, or the account or tenant is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformError" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid or expired token" } } } } }, "ErrForbidden": { "description": "Authenticated, but not allowed: wrong role, missing API-key scope, a missing or mismatched CSRF token on a cookie session, or MFA not yet set up (`MFA_ENROLLMENT_REQUIRED` — mandatory MFA).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformError" }, "example": { "error": { "code": "FORBIDDEN", "message": "Forbidden" } } } } }, "ErrNotFound": { "description": "The resource does not exist or does not belong to the caller's tenant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformError" }, "example": { "error": { "code": "NOT_FOUND", "message": "Not found" } } } } }, "ErrConflict": { "description": "The request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformError" }, "example": { "error": { "code": "CONFLICT", "message": "Conflict" } } } } }, "ErrUnprocessable": { "description": "Understood but rejected by a business rule or by the access point.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformError" }, "example": { "error": { "code": "AP_CORE_REJECTED", "message": "AP Core rejected submission" } } } } }, "ErrTooManyRequests": { "description": "Rate limit exceeded. Retry after the time in the `RateLimit-Reset` / `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformError" }, "example": { "error": { "code": "RATE_LIMITED", "message": "Too many requests" } } } } }, "ErrInternal": { "description": "Unexpected server error. No internal detail is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformError" }, "example": { "error": { "code": "INTERNAL", "message": "Internal server error" } } } } }, "ErrBadGateway": { "description": "An upstream service (access point, SMP, EmaraTax, object storage) failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformError" }, "example": { "error": { "code": "UPSTREAM", "message": "Upstream failure" } } } } }, "ErrUnavailable": { "description": "A required service or configuration is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformError" }, "example": { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service unavailable" } } } } }, "ValidationError": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "pintFailed": { "summary": "The document failed validation", "value": { "valid": false, "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:peppol:pint:billing-1@ae-1::2.1", "processId": "urn:peppol:bis:billing", "error": { "code": "PINT_VALIDATION_FAILED", "message": "Document failed Peppol/PINT validation.", "details": [ { "code": "PINT_BR_AE_20", "severity": "fatal", "message": "dueDate (IBT-009) is required when the amount due for payment is greater than zero [ibr-127-ae]", "xpath": "/dueDate" } ] } } } } } } }, "BadRequest": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "cursorMismatch": { "summary": "Cursor filter mismatch", "value": { "error": { "code": "CURSOR_FILTER_MISMATCH", "message": "Cursor was generated with different filters. Start a new query without a cursor." } } }, "invalidCursor": { "summary": "Invalid cursor format", "value": { "error": { "code": "INVALID_CURSOR", "message": "Invalid cursor format" } } } } } } }, "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" } } } } }, "Forbidden": { "description": "API key lacks required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "FORBIDDEN", "message": "Missing scope: transactions:read" } } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "NOT_FOUND", "message": "Transaction not found" } } } } }, "UpstreamError": { "description": "Access point rejected the submission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "apRejected": { "summary": "AP Core rejected submission", "value": { "error": { "code": "UPSTREAM", "message": "AP Core rejected submission", "details": { "transactionId": "txn_1715690640123_a1b2c3d4", "upstreamStatus": 400 } } } } } } } } }, "securitySchemes": { "ApiKeyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "AZDAN API Key", "description": "Tenant integration API key from the Tenant Console (API Keys): `Authorization: Bearer azd_live_…` or `azd_test_…`. Not a JWT. Each operation lists the scopes it accepts in `x-azdan-scopes` (any one suffices)." }, "BearerJWT": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Tenant user session token from `POST /api/auth/login` (or `POST /api/auth/mfa/verify` for accounts with MFA), sent as `Authorization: Bearer `. Valid for 8 hours. Bearer callers do not need a CSRF token. Roles: `tenant_admin`, `tenant_user`." }, "SessionCookie": { "type": "apiKey", "in": "cookie", "name": "azdan_session", "description": "The HTTP-only session cookie set by `POST /api/auth/login` (name configurable with `AUTH_COOKIE_NAME`, default `azdan_session`). Unsafe methods (POST/PUT/PATCH/DELETE) also need the `X-CSRF-Token` header equal to the readable `azdan_csrf` cookie." } } } }