{ "openapi": "3.0.3", "info": { "title": "Dativery Peppol API", "version": "1.0.0", "description": "Multi-tenant Peppol document exchange service. Most endpoints require Bearer token authentication obtained via POST /api/auth/login." }, "servers": [{ "url": "/api", "description": "Current server" }], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "SuccessWrapper": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object" } } }, "Tokens": { "type": "object", "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" } } }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Tenant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Participant": { "type": "object", "properties": { "id": { "type": "string" }, "tenantId": { "type": "string" }, "name": { "type": "string" }, "ico": { "type": "string", "nullable": true }, "countryCode": { "type": "string" }, "status": { "type": "string" }, "peppolIds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "peppolId": { "type": "string", "example": "0192:12345678" } } } }, "createdAt": { "type": "string", "format": "date-time" } } }, "Document": { "type": "object", "properties": { "id": { "type": "string" }, "participantId": { "type": "string" }, "direction": { "type": "string", "enum": ["inbound", "outbound"] }, "format": { "type": "string", "enum": ["ubl", "isdoc", "pohoda"] }, "documentType": { "type": "string" }, "senderPeppolId": { "type": "string" }, "receiverPeppolId": { "type": "string" }, "status": { "type": "string" }, "isRead": { "type": "boolean" }, "metadata": { "type": "object", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "PeppolLookupResult": { "type": "object", "properties": { "peppolId": { "type": "string", "example": "0192:12345678" }, "scheme": { "type": "string" }, "exists": { "type": "boolean" }, "capabilities": { "type": "object", "nullable": true, "properties": { "canReceiveInvoices": { "type": "boolean" }, "documentTypes": { "type": "array", "items": { "type": "string" } }, "endpoint": { "type": "string", "nullable": true } } }, "cachedAt": { "type": "string", "format": "date-time", "nullable": true }, "originalIdentifier": { "type": "string", "nullable": true } } } }, "responses": { "Unauthorized": { "description": "Unauthorized – missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "security": [{ "bearerAuth": [] }], "tags": [ { "name": "Health", "description": "Service health check" }, { "name": "Auth", "description": "Authentication and account management" }, { "name": "Lookup", "description": "Peppol network participant lookup" }, { "name": "Peppol", "description": "Send and receive Peppol documents" }, { "name": "Tenants", "description": "Tenant management" }, { "name": "Participants", "description": "Participant management within a tenant" }, { "name": "Webhooks", "description": "Webhook subscriptions" }, { "name": "Invitations", "description": "User invitations" } ], "paths": { "/health": { "get": { "tags": ["Health"], "summary": "Health check", "security": [], "responses": { "200": { "description": "Service status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": ["healthy", "degraded"] }, "version": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "checks": { "type": "object", "properties": { "database": { "type": "boolean" }, "redis": { "type": "boolean" }, "nats": { "type": "boolean" } } } } } } } } } } } } }, "/auth/register": { "post": { "tags": ["Auth"], "summary": "Register a new user", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 }, "firstName": { "type": "string" }, "lastName": { "type": "string" } } } } } }, "responses": { "201": { "description": "User registered successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "tokens": { "$ref": "#/components/schemas/Tokens" } } } } } } } } } } }, "/auth/login": { "post": { "tags": ["Auth"], "summary": "Login", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email", "password"], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" }, "otpCode": { "type": "string", "minLength": 6, "maxLength": 6, "description": "Required if 2FA is enabled" } } } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "tokens": { "$ref": "#/components/schemas/Tokens" } } } } } } } } } } }, "/auth/otp/setup": { "post": { "tags": ["Auth"], "summary": "Initiate 2FA setup – returns QR code", "responses": { "200": { "description": "OTP setup data", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "secret": { "type": "string" }, "qrCodeUrl": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/otp/verify": { "post": { "tags": ["Auth"], "summary": "Verify and activate 2FA", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["otpCode"], "properties": { "otpCode": { "type": "string", "minLength": 6, "maxLength": 6 } } } } } }, "responses": { "200": { "description": "2FA activated" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/otp/disable": { "post": { "tags": ["Auth"], "summary": "Disable 2FA", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["otpCode"], "properties": { "otpCode": { "type": "string", "minLength": 6, "maxLength": 6 } } } } } }, "responses": { "200": { "description": "2FA disabled" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/password/change": { "post": { "tags": ["Auth"], "summary": "Change password", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["currentPassword", "newPassword"], "properties": { "currentPassword": { "type": "string" }, "newPassword": { "type": "string", "minLength": 8 } } } } } }, "responses": { "200": { "description": "Password changed" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/password/reset/initiate": { "post": { "tags": ["Auth"], "summary": "Request a password reset e-mail", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Reset e-mail sent (if account exists)" } } } }, "/auth/password/reset/complete": { "post": { "tags": ["Auth"], "summary": "Complete a password reset", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["token", "newPassword"], "properties": { "token": { "type": "string" }, "newPassword": { "type": "string", "minLength": 8 } } } } } }, "responses": { "200": { "description": "Password reset successful" } } } }, "/lookup/cz/{ico}": { "get": { "tags": ["Lookup"], "summary": "Lookup by Czech IČO", "parameters": [ { "name": "ico", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{8}$" }, "example": "12345678" }, { "name": "documentType", "in": "query", "schema": { "type": "string", "default": "invoices" } } ], "responses": { "200": { "description": "Lookup result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/PeppolLookupResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/lookup/sk/{ico}": { "get": { "tags": ["Lookup"], "summary": "Lookup by Slovak IČO", "parameters": [ { "name": "ico", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{8}$" }, "example": "12345678" }, { "name": "documentType", "in": "query", "schema": { "type": "string", "default": "invoices" } } ], "responses": { "200": { "description": "Lookup result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/PeppolLookupResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/lookup/vat/{vatId}": { "get": { "tags": ["Lookup"], "summary": "Lookup by VAT ID", "parameters": [ { "name": "vatId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "CZ12345678" }, { "name": "documentType", "in": "query", "schema": { "type": "string", "default": "invoices" } } ], "responses": { "200": { "description": "Lookup result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/PeppolLookupResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/lookup/peppol/{peppolId}": { "get": { "tags": ["Lookup"], "summary": "Lookup by Peppol ID", "parameters": [ { "name": "peppolId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "0192:12345678" }, { "name": "documentType", "in": "query", "schema": { "type": "string", "default": "invoices" } } ], "responses": { "200": { "description": "Lookup result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/PeppolLookupResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/lookup/batch": { "post": { "tags": ["Lookup"], "summary": "Batch lookup (up to 50 identifiers)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["identifiers"], "properties": { "identifiers": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "example": ["CZ12345678", "0192:87654321"] }, "documentType": { "type": "string", "default": "invoices" } } } } } }, "responses": { "200": { "description": "Batch results" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/peppol/inbox": { "get": { "tags": ["Peppol"], "summary": "Get unread inbound documents", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "participantId", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of unread documents" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/peppol/documents": { "get": { "tags": ["Peppol"], "summary": "List documents", "parameters": [ { "name": "direction", "in": "query", "schema": { "type": "string", "enum": ["inbound", "outbound"] } }, { "name": "participantId", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Document list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "total": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/peppol/documents/{documentId}/status": { "get": { "tags": ["Peppol"], "summary": "Get document delivery status", "parameters": [{ "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Document status" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/peppol/documents/{documentId}/mark-read": { "post": { "tags": ["Peppol"], "summary": "Mark a document as read", "parameters": [{ "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Marked as read" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/peppol/documents/{documentId}/download": { "get": { "tags": ["Peppol"], "summary": "Download document as XML", "parameters": [{ "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Raw XML content", "content": { "application/xml": {} } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/peppol/documents/{documentId}/isdoc": { "get": { "tags": ["Peppol"], "summary": "Download document converted to ISDOC", "parameters": [{ "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "ISDOC XML", "content": { "application/xml": {} } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/peppol/documents/{documentId}/pohoda": { "get": { "tags": ["Peppol"], "summary": "Download document converted to Pohoda XML", "parameters": [{ "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Pohoda XML", "content": { "application/xml": {} } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/peppol/{companyId}/send": { "post": { "tags": ["Peppol"], "summary": "Send a UBL document via Peppol", "parameters": [{ "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Participant (company) ID" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["receiverPeppolId", "documentTypeIdentifier", "processIdentifier", "content"], "properties": { "receiverPeppolId": { "type": "string", "example": "0192:87654321" }, "documentTypeIdentifier": { "type": "string", "example": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1" }, "processIdentifier": { "type": "string", "example": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0" }, "content": { "type": "string", "description": "Base64-encoded UBL XML" }, "metadata": { "type": "object" } } } } } }, "responses": { "200": { "description": "Document sent successfully" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/peppol/{companyId}/send/isdoc": { "post": { "tags": ["Peppol"], "summary": "Send an ISDOC document (auto-converted to UBL)", "parameters": [{ "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["receiverPeppolId", "content"], "properties": { "receiverPeppolId": { "type": "string", "example": "0192:87654321" }, "content": { "type": "string", "description": "Base64-encoded ISDOC XML" }, "metadata": { "type": "object" } } } } } }, "responses": { "200": { "description": "Document sent successfully" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/peppol/{companyId}/send/pohoda": { "post": { "tags": ["Peppol"], "summary": "Send a Pohoda XML document (auto-converted to UBL)", "parameters": [{ "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["receiverPeppolId", "content"], "properties": { "receiverPeppolId": { "type": "string", "example": "0192:87654321" }, "content": { "type": "string", "description": "Base64-encoded Pohoda XML" }, "metadata": { "type": "object" } } } } } }, "responses": { "200": { "description": "Document sent successfully" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/peppol/{companyId}/verify": { "get": { "tags": ["Peppol"], "summary": "Verify a receiver can accept documents", "parameters": [ { "name": "companyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "receiverPeppolId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification result" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tenants": { "get": { "tags": ["Tenants"], "summary": "List tenants for the current user", "responses": { "200": { "description": "Tenant list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "tenants": { "type": "array", "items": { "$ref": "#/components/schemas/Tenant" } }, "count": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Tenants"], "summary": "Create a new tenant", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } } } } }, "responses": { "201": { "description": "Tenant created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Tenant" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tenants/{tenantId}": { "get": { "tags": ["Tenants"], "summary": "Get tenant details", "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Tenant details" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": ["Tenants"], "summary": "Update tenant (admin only)", "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Tenant updated" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "delete": { "tags": ["Tenants"], "summary": "Delete tenant (admin only)", "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Tenant deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tenants/{tenantId}/users": { "get": { "tags": ["Tenants"], "summary": "List users in a tenant (admin only)", "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "User list" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Tenants"], "summary": "Add a user to tenant (admin only)", "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["userId", "role"], "properties": { "userId": { "type": "string" }, "role": { "type": "string", "enum": ["admin", "member"] } } } } } }, "responses": { "201": { "description": "User added" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tenants/{tenantId}/users/{userId}": { "delete": { "tags": ["Tenants"], "summary": "Remove a user from tenant (admin only)", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User removed" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tenants/{tenantId}/participants": { "get": { "tags": ["Participants"], "summary": "List participants", "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Participant list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Participants"], "summary": "Create a participant (admin only)", "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "countryCode"], "properties": { "name": { "type": "string" }, "ico": { "type": "string" }, "countryCode": { "type": "string", "example": "CZ" } } } } } }, "responses": { "201": { "description": "Participant created" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tenants/{tenantId}/participants/{participantId}": { "get": { "tags": ["Participants"], "summary": "Get participant details", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "participantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Participant details" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": ["Participants"], "summary": "Update participant (admin only)", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "participantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Participant updated" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "delete": { "tags": ["Participants"], "summary": "Delete participant (admin only)", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "participantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Participant deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tenants/{tenantId}/participants/{participantId}/peppol-ids": { "get": { "tags": ["Participants"], "summary": "List Peppol IDs for participant", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "participantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Peppol ID list" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Participants"], "summary": "Register a Peppol ID for participant", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "participantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["peppolId"], "properties": { "peppolId": { "type": "string", "example": "0192:12345678" } } } } } }, "responses": { "201": { "description": "Peppol ID registered" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tenants/{tenantId}/participants/{participantId}/verify/initiate": { "post": { "tags": ["Participants"], "summary": "Initiate participant company verification wizard", "description": "Multi-step verification flow: (1) email verified, (2a) business identity via ARES/ADISSPR, (2b) bank payment 25 CZK from ADISSPR-registered account, (3+) authorized person, phone, PEPPOL. Returns current stage with per-stage issues and optional QR code HTML for payment step.", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "participantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": ["cs", "en", "sk"], "default": "cs" }, "description": "Language for email notifications and error messages" } ], "security": [{ "BearerAuth": [] }], "responses": { "200": { "description": "Verification status with staged summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "currentStage": { "type": "string", "enum": ["EMAIL", "REGISTRATION", "BANK_ACCOUNT", "AUTHORIZED_PERSON", "PHONE", "PEPPOL"], "description": "The first incomplete verification stage" }, "stages": { "type": "object", "description": "Summary of each verification stage", "additionalProperties": { "type": "object", "properties": { "completed": { "type": "boolean" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code", "example": "ARES_DIC_MISMATCH" }, "message": { "type": "string", "description": "Human-readable error message" } } } } } } }, "verification": { "nullable": true, "type": "object", "description": "Present only when BANK_ACCOUNT stage is active and a pending payment verification exists", "properties": { "verificationId": { "type": "string", "format": "uuid" }, "variableSymbol": { "type": "string", "example": "9987654321", "description": "10-digit payment variable symbol starting with 99" }, "amount": { "type": "number", "example": 25.0 }, "currency": { "type": "string", "example": "CZK" }, "expiresAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": ["pending", "verified", "expired", "refunded", "pending_review"] }, "qrCodeDataUrl": { "type": "string", "description": "Base64 PNG data URL of SPAYD ePlatby QR code" }, "qrCodeHtml": { "type": "string", "description": "Ready-to-embed HTML img tag for the QR code" } } } } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "emailNotVerified": { "value": { "success": false, "error": { "code": "EMAIL_NOT_VERIFIED", "message": "User email must be verified before initiating company verification" } } }, "missingRegistrationId": { "value": { "success": false, "error": { "code": "MISSING_REGISTRATION_ID", "message": "Participant must have a registrationNumber or taxId set" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Participant not found" } } } }, "/tenants/{tenantId}/participants/{participantId}/verify/status": { "get": { "tags": ["Participants"], "summary": "Get participant verification status", "parameters": [ { "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "participantId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification status" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tenants/{tenantId}/certificates": { "get": { "tags": ["Tenants"], "summary": "List certificates for a tenant", "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Certificate list" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Tenants"], "summary": "Upload a certificate", "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Certificate uploaded" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/tenants/{tenantId}/api-keys": { "get": { "tags": ["Tenants"], "summary": "List API keys for a tenant", "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "API key list" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Tenants"], "summary": "Create an API key", "parameters": [{ "name": "tenantId", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" } } } } } }, "responses": { "201": { "description": "API key created" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/webhooks": { "get": { "tags": ["Webhooks"], "summary": "List webhooks", "responses": { "200": { "description": "Webhook list" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Webhooks"], "summary": "Register a webhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["type", "events"], "properties": { "participantId": { "type": "string" }, "type": { "type": "string", "enum": ["http", "email", "sms"] }, "url": { "type": "string", "format": "uri", "description": "Required for type=http" }, "email": { "type": "string", "format": "email", "description": "Required for type=email" }, "phone": { "type": "string", "description": "Required for type=sms" }, "events": { "type": "array", "items": { "type": "string" }, "example": ["document.received", "document.sent"] } } } } } }, "responses": { "201": { "description": "Webhook registered" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/webhooks/{webhookId}": { "patch": { "tags": ["Webhooks"], "summary": "Update a webhook", "parameters": [{ "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Webhook updated" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "delete": { "tags": ["Webhooks"], "summary": "Delete a webhook", "parameters": [{ "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Webhook deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/invitations": { "post": { "tags": ["Invitations"], "summary": "Create an invitation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" }, "tenantId": { "type": "string" }, "role": { "type": "string", "enum": ["admin", "member"] } } } } } }, "responses": { "201": { "description": "Invitation created" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/invitations/{token}/accept": { "post": { "tags": ["Invitations"], "summary": "Accept an invitation", "security": [], "parameters": [{ "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Invitation accepted" } } } } } }