{ "openapi": "3.0.4", "info": { "title": "Firme · Company Registry API", "description": "Authenticated company lookup with per-account allowances. Obtain a short-lived Bearer access token using a verified account. Refresh tokens rotate and reuse revokes the session. Anonymous demo contains fictional records only.", "version": "v1" }, "servers": [ { "url": "/", "description": "Current host" }, { "url": "https://firme.kvadrati.com", "description": "Configured API root" } ], "paths": { "/api/auth/me": { "get": { "tags": [ "Account" ], "summary": "Read account and remaining quota", "description": "Read effective plan, daily usage and next reset without consuming lookup allowance. Expired paid plans fall back to Free. used/remaining are a snapshot, not reserved slots; concurrent requests can change them. Daily reset uses Europe/Ljubljana including DST.\n\nIP protection: 300 requests/minute globally. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### Account dashboard\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/auth/me' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/auth/me\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/auth/me\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Check current quota\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/auth/me' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/auth/me\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/auth/me\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "GetAccount", "responses": { "200": { "description": "Effective account, plan and daily quota. During support, support contains id, actorName, actorEmail, targetName, targetEmail and expiresAt; isSuperadmin is false. Otherwise support is null.", "content": { "application/json": { "schema": { "required": [ "id", "email", "name", "plan", "used", "remaining", "resetAt", "support" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "email": { "type": "string", "description": "Authenticated account email." }, "name": { "type": "string", "description": "Company legal name or account display name, depending on response." }, "plan": { "required": [ "id", "daily", "perMinute", "concurrent" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "daily": { "type": "integer", "description": "Maximum accepted lookups per Ljubljana calendar day." }, "perMinute": { "type": "integer", "description": "Per-account minute cap." }, "concurrent": { "type": "integer", "description": "Maximum simultaneous account lookups." } }, "description": "Effective account plan or purchased plan identifier." }, "used": { "type": "integer", "description": "Accepted lookups used today." }, "remaining": { "type": "integer", "description": "Daily remaining allowance at response time; not a reservation." }, "resetAt": { "type": "string", "description": "Next applicable reset timestamp with timezone.", "format": "date-time" }, "support": { "type": "string", "nullable": true } } }, "examples": { "success": { "summary": "success", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "email": "developer@example.com", "name": "Example User", "plan": { "id": "free", "daily": 5, "perMinute": 5, "concurrent": 1 }, "used": 2, "remaining": 3, "resetAt": "2026-10-23T00:00:00+02:00" } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/auth/me", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/auth/me", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/auth/me", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } } } }, "/api/auth/support-session/stop": { "post": { "tags": [ "Account" ], "summary": "Return to administration", "description": "Return to administration. Working as · . Administrator actions remain recorded.\n\n### StopSupportSession\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\nusing var client = new HttpClient(new HttpClientHandler { UseCookies = true });\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/auth/support-session/stop\");\nrequest.Headers.TryAddWithoutValidation(\"Origin\", \"http://localhost:5278\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer YOUR_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nresponse.EnsureSuccessStatusCode();\n// Keep the same HttpClient/CookieContainer for subsequent requests and stopping support.\n```\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/auth/support-session/stop' --header 'Origin: http://localhost:5278' --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' --header 'Content-Type: application/json' --cookie cookies.txt --cookie-jar cookies.txt\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/auth/support-session/stop\", {method:\"POST\", credentials:\"same-origin\", headers:{Authorization:\"Bearer \" + accessToken,\"Content-Type\":\"application/json\"}}); if(!response.ok) throw new Error(\"Support session request failed\");\n```", "operationId": "StopSupportSession", "parameters": [ { "name": "Origin", "in": "header", "description": "Exact service scheme and host, including local port. Required for CAPTCHA submissions and cookie-based refresh. Browser supplies it automatically.", "required": true, "schema": { "type": "string" }, "example": "http://localhost:5278" } ], "responses": { "204": { "description": "Support context closed and cookie cleared. Original administrator login remains unchanged." }, "400": { "description": "validationError: Please check the information you entered.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/auth/support-session/stop", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/auth/support-session/stop", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "403": { "description": "forbidden: Access denied", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "forbidden": { "summary": "forbidden", "description": "Access denied", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Access denied", "status": 403, "detail": "Access denied", "instance": "/api/auth/support-session/stop", "code": "forbidden", "traceId": "00-example-trace-id", "message": "Access denied" } } } } } }, "409": { "description": "orderConflict: Order data conflicts with the saved order/event. Retry the original details.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "orderConflict": { "summary": "orderConflict", "description": "Order data conflicts with the saved order/event. Retry the original details.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request conflict", "status": 409, "detail": "Order data conflicts with the saved order/event. Retry the original details.", "instance": "/api/auth/support-session/stop", "code": "orderConflict", "traceId": "00-example-trace-id", "message": "Order data conflicts with the saved order/event. Retry the original details." } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/auth/support-session/stop", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/auth/support-session/stop", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } }, "security": [ ] } }, "/api/registration/confirm": { "post": { "tags": [ "Account" ], "summary": "Confirm registration email", "description": "Consume the single-use 24-hour token from the email link. Enables login and queues exactly one admin notification to hello@kvadrati.com. Invalid, expired or reused tokens return 400. Does not issue access tokens: log in afterwards.\n\nIP protection: 300 requests/minute globally, plus a shared 5/minute route policy. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### Confirm email\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/registration/confirm' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"token\": \"REPLACE_WITH_EMAIL_TOKEN\"}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/registration/confirm\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({\"token\": \"REPLACE_WITH_EMAIL_TOKEN\"})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/registration/confirm\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"token\": \"REPLACE_WITH_EMAIL_TOKEN\"\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Invalid-token example (400)\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/registration/confirm' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"token\": \"invalid-example-token\"}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/registration/confirm\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({\"token\": \"invalid-example-token\"})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/registration/confirm\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"token\": \"invalid-example-token\"\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "ConfirmRegistration", "requestBody": { "description": "Required token from confirmation link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Confirmation" }, "examples": { "Confirm email": { "summary": "Confirm email", "value": { "token": "REPLACE_WITH_EMAIL_TOKEN" } }, "Invalid-token example (400)": { "summary": "Invalid-token example (400)", "value": { "token": "invalid-example-token" } } } } }, "required": true }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "required": [ "code" ], "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable outcome or error code." } } }, "examples": { "success": { "summary": "success", "value": { "code": "confirmed" } } } } } }, "400": { "description": "validationError: Please check the information you entered.; confirmationInvalid: The link is invalid or expired.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/registration/confirm", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "token": [ "Supply the email token, up to 128 characters." ] } } }, "confirmationInvalid": { "summary": "confirmationInvalid", "description": "The link is invalid or expired.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "The link is invalid or expired.", "instance": "/api/registration/confirm", "code": "confirmationInvalid", "traceId": "00-example-trace-id", "message": "The link is invalid or expired.", "errors": { "token": [ "The link is invalid or expired." ] } } } } } } }, "413": { "description": "payloadTooLarge: Request too large", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "payloadTooLarge": { "summary": "payloadTooLarge", "description": "Request too large", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request too large", "status": 413, "detail": "Request too large", "instance": "/api/registration/confirm", "code": "payloadTooLarge", "traceId": "00-example-trace-id", "message": "Request too large" } } } } } }, "415": { "description": "unsupportedMediaType: Unsupported content type", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unsupportedMediaType": { "summary": "unsupportedMediaType", "description": "Unsupported content type", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Unsupported content type", "status": 415, "detail": "Unsupported content type", "instance": "/api/registration/confirm", "code": "unsupportedMediaType", "traceId": "00-example-trace-id", "message": "Unsupported content type" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/registration/confirm", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/registration/confirm", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } }, "security": [ ] } }, "/api/auth/register": { "post": { "tags": [ "Account" ], "summary": "Register and request email verification", "description": "Create an account and queue a verification email. Confirm within 24 hours before login. Repeated email addresses receive generic 202 to prevent account enumeration. Confirmation queues one admin notification. Requires exact same-origin Origin and fresh Turnstile action register. DemoMode returns 503.\n\nIP protection: 300 requests/minute globally, plus a shared 5/minute route policy. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### individual\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/auth/register' \\\n --header 'Content-Type: application/json' \\\n --header 'Origin: http://localhost:5278' \\\n --data-raw '{\"name\": \"Example User\", \"email\": \"developer@example.com\", \"password\": \"Replace-this-password-123!\", \"locale\": \"en\", \"turnstileToken\": \"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\", \"billing\": {\"customerType\": \"individual\", \"billingName\": \"Example User\", \"street\": \"\", \"postalCode\": \"1000\", \"city\": \"Ljubljana\", \"countryCode\": \"SI\", \"taxNumber\": \"\", \"vatStatus\": \"none\"}}'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/auth/register\", {\"method\": \"POST\", \"headers\": {\"Content-Type\": \"application/json\"}, \"body\": \"{\\\"name\\\": \\\"Example User\\\", \\\"email\\\": \\\"developer@example.com\\\", \\\"password\\\": \\\"Replace-this-password-123!\\\", \\\"locale\\\": \\\"en\\\", \\\"turnstileToken\\\": \\\"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\\\", \\\"billing\\\": {\\\"customerType\\\": \\\"individual\\\", \\\"billingName\\\": \\\"Example User\\\", \\\"street\\\": \\\"\\\", \\\"postalCode\\\": \\\"1000\\\", \\\"city\\\": \\\"Ljubljana\\\", \\\"countryCode\\\": \\\"SI\\\", \\\"taxNumber\\\": \\\"\\\", \\\"vatStatus\\\": \\\"none\\\"}}\"});\nif (!response.ok) throw new Error(await response.text());\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/auth/register\");\nrequest.Headers.TryAddWithoutValidation(\"Origin\", \"http://localhost:5278\");\nrequest.Content = new StringContent(\"{\\\"name\\\": \\\"Example User\\\", \\\"email\\\": \\\"developer@example.com\\\", \\\"password\\\": \\\"Replace-this-password-123!\\\", \\\"locale\\\": \\\"en\\\", \\\"turnstileToken\\\": \\\"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\\\", \\\"billing\\\": {\\\"customerType\\\": \\\"individual\\\", \\\"billingName\\\": \\\"Example User\\\", \\\"street\\\": \\\"\\\", \\\"postalCode\\\": \\\"1000\\\", \\\"city\\\": \\\"Ljubljana\\\", \\\"countryCode\\\": \\\"SI\\\", \\\"taxNumber\\\": \\\"\\\", \\\"vatStatus\\\": \\\"none\\\"}}\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```\n\n### company\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/auth/register' \\\n --header 'Content-Type: application/json' \\\n --header 'Origin: http://localhost:5278' \\\n --data-raw '{\"name\": \"Example User\", \"email\": \"developer@example.com\", \"password\": \"Replace-this-password-123!\", \"locale\": \"en\", \"turnstileToken\": \"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\", \"billing\": {\"customerType\": \"company\", \"billingName\": \"Example d.o.o.\", \"street\": \"Example 1\", \"postalCode\": \"1000\", \"city\": \"Ljubljana\", \"countryCode\": \"SI\", \"taxNumber\": \"SI12345678\", \"vatStatus\": \"registered\"}}'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/auth/register\", {\"method\": \"POST\", \"headers\": {\"Content-Type\": \"application/json\"}, \"body\": \"{\\\"name\\\": \\\"Example User\\\", \\\"email\\\": \\\"developer@example.com\\\", \\\"password\\\": \\\"Replace-this-password-123!\\\", \\\"locale\\\": \\\"en\\\", \\\"turnstileToken\\\": \\\"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\\\", \\\"billing\\\": {\\\"customerType\\\": \\\"company\\\", \\\"billingName\\\": \\\"Example d.o.o.\\\", \\\"street\\\": \\\"Example 1\\\", \\\"postalCode\\\": \\\"1000\\\", \\\"city\\\": \\\"Ljubljana\\\", \\\"countryCode\\\": \\\"SI\\\", \\\"taxNumber\\\": \\\"SI12345678\\\", \\\"vatStatus\\\": \\\"registered\\\"}}\"});\nif (!response.ok) throw new Error(await response.text());\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/auth/register\");\nrequest.Headers.TryAddWithoutValidation(\"Origin\", \"http://localhost:5278\");\nrequest.Content = new StringContent(\"{\\\"name\\\": \\\"Example User\\\", \\\"email\\\": \\\"developer@example.com\\\", \\\"password\\\": \\\"Replace-this-password-123!\\\", \\\"locale\\\": \\\"en\\\", \\\"turnstileToken\\\": \\\"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\\\", \\\"billing\\\": {\\\"customerType\\\": \\\"company\\\", \\\"billingName\\\": \\\"Example d.o.o.\\\", \\\"street\\\": \\\"Example 1\\\", \\\"postalCode\\\": \\\"1000\\\", \\\"city\\\": \\\"Ljubljana\\\", \\\"countryCode\\\": \\\"SI\\\", \\\"taxNumber\\\": \\\"SI12345678\\\", \\\"vatStatus\\\": \\\"registered\\\"}}\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```", "operationId": "RegisterAccount", "parameters": [ { "name": "Origin", "in": "header", "description": "Exact service scheme and host, including local port. Required for CAPTCHA submissions and cookie-based refresh. Browser supplies it automatically.", "required": true, "schema": { "type": "string" }, "example": "http://localhost:5278" } ], "requestBody": { "description": "Required: name, email, password, locale, Turnstile and billing. Individuals provide city, postal code and country, without street or tax number. Companies also provide their legal name, street, tax number and VAT status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterInput" }, "examples": { "individual": { "summary": "individual", "value": { "name": "Example User", "email": "developer@example.com", "password": "Replace-this-password-123!", "locale": "en", "turnstileToken": "REPLACE_WITH_FRESH_TURNSTILE_TOKEN", "billing": { "customerType": "individual", "billingName": "Example User", "street": "", "postalCode": "1000", "city": "Ljubljana", "countryCode": "SI", "taxNumber": "", "vatStatus": "none" } } }, "company": { "summary": "company", "value": { "name": "Example User", "email": "developer@example.com", "password": "Replace-this-password-123!", "locale": "en", "turnstileToken": "REPLACE_WITH_FRESH_TURNSTILE_TOKEN", "billing": { "customerType": "company", "billingName": "Example d.o.o.", "street": "Example 1", "postalCode": "1000", "city": "Ljubljana", "countryCode": "SI", "taxNumber": "SI12345678", "vatStatus": "registered" } } } } } }, "required": true }, "responses": { "202": { "description": "Accepted; verification queued where applicable. Does not guarantee delivery.", "content": { "application/json": { "schema": { "required": [ "message" ], "type": "object", "properties": { "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." } } }, "examples": { "success": { "summary": "success", "value": { "message": "Check your email to confirm registration." } } } } } }, "400": { "description": "validationError: Please check the information you entered.; captchaError: Complete verification and try again.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/auth/register", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "name": [ "Enter a name of 1–200 characters." ], "email": [ "Enter a valid email, at most 254 characters." ], "password": [ "Use 12–128 password characters." ], "locale": [ "Choose sl, hr, en, sr-Cyrl or bs." ] } } }, "captchaError": { "summary": "captchaError", "description": "Complete verification and try again.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Complete verification and try again.", "instance": "/api/auth/register", "code": "captchaError", "traceId": "00-example-trace-id", "message": "Complete verification and try again.", "errors": { "turnstileToken": [ "Complete verification and try again." ] } } } } } } }, "413": { "description": "payloadTooLarge: Request too large", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "payloadTooLarge": { "summary": "payloadTooLarge", "description": "Request too large", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request too large", "status": 413, "detail": "Request too large", "instance": "/api/auth/register", "code": "payloadTooLarge", "traceId": "00-example-trace-id", "message": "Request too large" } } } } } }, "415": { "description": "unsupportedMediaType: Unsupported content type", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unsupportedMediaType": { "summary": "unsupportedMediaType", "description": "Unsupported content type", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Unsupported content type", "status": 415, "detail": "Unsupported content type", "instance": "/api/auth/register", "code": "unsupportedMediaType", "traceId": "00-example-trace-id", "message": "Unsupported content type" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/auth/register", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable; demoFormsDisabled: Forms are disabled in demo mode.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/auth/register", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } }, "demoFormsDisabled": { "summary": "demoFormsDisabled", "description": "Forms are disabled in demo mode.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Forms are disabled in demo mode.", "instance": "/api/auth/register", "code": "demoFormsDisabled", "traceId": "00-example-trace-id", "message": "Forms are disabled in demo mode." } } } } } } }, "security": [ ] } }, "/api/auth/login": { "post": { "tags": [ "Account" ], "summary": "Sign in and obtain tokens", "description": "Authenticate a confirmed, enabled account. Returns a 15-minute opaque access token and rotating refresh token, and sets the HttpOnly SameSite=Strict refresh cookie. Absolute session lifetime: 30 days. Unknown, unconfirmed, disabled, locked and incorrect-password cases all return 401. Five failed attempts trigger lockout. Keep browser access tokens in memory and never log either token. Responses are no-store.\n\nIP protection: 300 requests/minute globally, plus a shared 5/minute route policy. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### Sign in\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/auth/login' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"email\": \"developer@example.com\", \"password\": \"Replace-this-password-123!\", \"locale\": \"en\"}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/auth/login\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({\"email\": \"developer@example.com\", \"password\": \"Replace-this-password-123!\", \"locale\": \"en\"})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/auth/login\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"email\": \"developer@example.com\",\n \"password\": \"Replace-this-password-123!\",\n \"locale\": \"en\"\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Minimal body\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/auth/login' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"email\": \"developer@example.com\", \"password\": \"Replace-this-password-123!\"}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/auth/login\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({\"email\": \"developer@example.com\", \"password\": \"Replace-this-password-123!\"})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/auth/login\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"email\": \"developer@example.com\",\n \"password\": \"Replace-this-password-123!\"\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "LoginAccount", "requestBody": { "description": "Required email/password; optional locale defaults to en.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginInput" }, "examples": { "Sign in": { "summary": "Sign in", "value": { "email": "developer@example.com", "password": "Replace-this-password-123!", "locale": "en" } }, "Minimal body": { "summary": "Minimal body", "value": { "email": "developer@example.com", "password": "Replace-this-password-123!" } } } } }, "required": true }, "responses": { "200": { "description": "Successful response.", "headers": { "Set-Cookie": { "description": "HttpOnly SameSite=Strict refresh cookie scoped to /api/auth; Secure on HTTPS. Logout clears it.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "required": [ "accessToken", "refreshToken", "tokenType", "expiresIn" ], "type": "object", "properties": { "accessToken": { "type": "string", "description": "Opaque Bearer access token, valid for expiresIn seconds. Keep secret; browser memory only." }, "refreshToken": { "type": "string", "description": "Secret rotating refresh token. Replace after every successful refresh." }, "tokenType": { "type": "string", "description": "Bearer." }, "expiresIn": { "type": "integer", "description": "Access lifetime in seconds (900)." } } }, "examples": { "success": { "summary": "success", "value": { "accessToken": "REPLACE_WITH_ACCESS_TOKEN", "refreshToken": "REPLACE_WITH_REFRESH_TOKEN", "tokenType": "Bearer", "expiresIn": 900 } } } } } }, "400": { "description": "validationError: Please check the information you entered.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/auth/login", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "email": [ "Enter a valid email, at most 254 characters." ], "password": [ "Use 12–128 password characters." ], "locale": [ "Choose sl, hr, en, sr-Cyrl or bs." ] } } } } } } }, "401": { "description": "loginFailed: Sign-in failed. Check your details and email verification or try again later.", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "loginFailed": { "summary": "loginFailed", "description": "Sign-in failed. Check your details and email verification or try again later.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Sign-in failed. Check your details and email verification or try again later.", "instance": "/api/auth/login", "code": "loginFailed", "traceId": "00-example-trace-id", "message": "Sign-in failed. Check your details and email verification or try again later." } } } } } }, "413": { "description": "payloadTooLarge: Request too large", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "payloadTooLarge": { "summary": "payloadTooLarge", "description": "Request too large", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request too large", "status": 413, "detail": "Request too large", "instance": "/api/auth/login", "code": "payloadTooLarge", "traceId": "00-example-trace-id", "message": "Request too large" } } } } } }, "415": { "description": "unsupportedMediaType: Unsupported content type", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unsupportedMediaType": { "summary": "unsupportedMediaType", "description": "Unsupported content type", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Unsupported content type", "status": 415, "detail": "Unsupported content type", "instance": "/api/auth/login", "code": "unsupportedMediaType", "traceId": "00-example-trace-id", "message": "Unsupported content type" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/auth/login", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/auth/login", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } }, "security": [ ] } }, "/api/auth/refresh": { "post": { "tags": [ "Account" ], "summary": "Rotate access and refresh tokens", "description": "Exchange the refresh token once and replace BOTH stored tokens. Old access tokens stop working. Replaying a consumed refresh token revokes the entire session. API clients send refreshToken; same-origin browsers send {} with the HttpOnly cookie and Origin. Serialize refresh attempts to avoid replay races. Rotation neither resets quota nor extends the absolute 30-day session expiry.\n\nIP protection: 300 requests/minute globally, plus a shared 5/minute route policy. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### API refresh token\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/auth/refresh' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"refreshToken\": \"REPLACE_WITH_REFRESH_TOKEN\"}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/auth/refresh\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({\"refreshToken\": \"REPLACE_WITH_REFRESH_TOKEN\"})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/auth/refresh\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"refreshToken\": \"REPLACE_WITH_REFRESH_TOKEN\"\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Same-origin cookie refresh\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/auth/refresh' \\\n --header 'Accept: application/json' \\\n --header 'Origin: http://localhost:5278' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{}' \\\n --cookie cookies.txt # Cookie jar saved from login with --cookie-jar cookies.txt\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/auth/refresh\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/auth/refresh\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Origin\", \"http://localhost:5278\");\nrequest.Content = new StringContent(\"\"\"\n{}\n\"\"\", Encoding.UTF8, \"application/json\");\n// Reuse the HttpClientHandler/CookieContainer from login in an actual cookie session.\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "RefreshSession", "requestBody": { "description": "JSON body required, even in cookie mode: {}. refreshToken is optional.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshInput" }, "examples": { "API refresh token": { "summary": "API refresh token", "value": { "refreshToken": "REPLACE_WITH_REFRESH_TOKEN" } }, "Same-origin cookie refresh": { "summary": "Same-origin cookie refresh", "value": { } } } } }, "required": true }, "responses": { "200": { "description": "Successful response.", "headers": { "Set-Cookie": { "description": "HttpOnly SameSite=Strict refresh cookie scoped to /api/auth; Secure on HTTPS. Logout clears it.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "required": [ "accessToken", "refreshToken", "tokenType", "expiresIn" ], "type": "object", "properties": { "accessToken": { "type": "string", "description": "Opaque Bearer access token, valid for expiresIn seconds. Keep secret; browser memory only." }, "refreshToken": { "type": "string", "description": "Secret rotating refresh token. Replace after every successful refresh." }, "tokenType": { "type": "string", "description": "Bearer." }, "expiresIn": { "type": "integer", "description": "Access lifetime in seconds (900)." } } }, "examples": { "success": { "summary": "success", "value": { "accessToken": "REPLACE_WITH_ACCESS_TOKEN", "refreshToken": "REPLACE_WITH_REFRESH_TOKEN", "tokenType": "Bearer", "expiresIn": 900 } } } } } }, "400": { "description": "validationError: Please check the information you entered.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/auth/refresh", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "request": [ "Check the documented required fields." ] } } } } } } }, "401": { "description": "loginFailed: Sign-in failed. Check your details and email verification or try again later.", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "loginFailed": { "summary": "loginFailed", "description": "Sign-in failed. Check your details and email verification or try again later.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Sign-in failed. Check your details and email verification or try again later.", "instance": "/api/auth/refresh", "code": "loginFailed", "traceId": "00-example-trace-id", "message": "Sign-in failed. Check your details and email verification or try again later." } } } } } }, "413": { "description": "payloadTooLarge: Request too large", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "payloadTooLarge": { "summary": "payloadTooLarge", "description": "Request too large", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request too large", "status": 413, "detail": "Request too large", "instance": "/api/auth/refresh", "code": "payloadTooLarge", "traceId": "00-example-trace-id", "message": "Request too large" } } } } } }, "415": { "description": "unsupportedMediaType: Unsupported content type", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unsupportedMediaType": { "summary": "unsupportedMediaType", "description": "Unsupported content type", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Unsupported content type", "status": 415, "detail": "Unsupported content type", "instance": "/api/auth/refresh", "code": "unsupportedMediaType", "traceId": "00-example-trace-id", "message": "Unsupported content type" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/auth/refresh", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/auth/refresh", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } }, "security": [ ] } }, "/api/auth/forgot-password": { "post": { "tags": [ "Account" ], "summary": "Request password recovery", "description": "Queue a one-hour reset link for eligible accounts. Valid requests always receive generic 202, including unknown email addresses. Per-account issuance is throttled. Requires same-origin Origin and fresh Turnstile action forgot. DemoMode returns 503.\n\nIP protection: 300 requests/minute globally, plus a shared 5/minute route policy. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### English recovery\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/auth/forgot-password' \\\n --header 'Accept: application/json' \\\n --header 'Origin: http://localhost:5278' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"email\": \"developer@example.com\", \"locale\": \"en\", \"turnstileToken\": \"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\"}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/auth/forgot-password\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({\"email\": \"developer@example.com\", \"locale\": \"en\", \"turnstileToken\": \"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\"})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/auth/forgot-password\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Origin\", \"http://localhost:5278\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"email\": \"developer@example.com\",\n \"locale\": \"en\",\n \"turnstileToken\": \"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\"\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Croatian recovery\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/auth/forgot-password' \\\n --header 'Accept: application/json' \\\n --header 'Origin: http://localhost:5278' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"email\": \"developer@example.com\", \"locale\": \"hr\", \"turnstileToken\": \"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\"}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/auth/forgot-password\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({\"email\": \"developer@example.com\", \"locale\": \"hr\", \"turnstileToken\": \"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\"})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/auth/forgot-password\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Origin\", \"http://localhost:5278\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"email\": \"developer@example.com\",\n \"locale\": \"hr\",\n \"turnstileToken\": \"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\"\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "ForgotPassword", "parameters": [ { "name": "Origin", "in": "header", "description": "Exact service scheme and host, including local port. Required for CAPTCHA submissions and cookie-based refresh. Browser supplies it automatically.", "required": true, "schema": { "type": "string" }, "example": "http://localhost:5278" } ], "requestBody": { "description": "Required email, locale and turnstileToken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotInput" }, "examples": { "English recovery": { "summary": "English recovery", "value": { "email": "developer@example.com", "locale": "en", "turnstileToken": "REPLACE_WITH_FRESH_TURNSTILE_TOKEN" } }, "Croatian recovery": { "summary": "Croatian recovery", "value": { "email": "developer@example.com", "locale": "hr", "turnstileToken": "REPLACE_WITH_FRESH_TURNSTILE_TOKEN" } } } } }, "required": true }, "responses": { "202": { "description": "Successful response.", "content": { "application/json": { "schema": { "required": [ "message" ], "type": "object", "properties": { "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." } } }, "examples": { "success": { "summary": "success", "value": { "message": "If eligible, a reset link will be sent." } } } } } }, "400": { "description": "validationError: Please check the information you entered.; captchaError: Complete verification and try again.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/auth/forgot-password", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "email": [ "Enter a valid email, at most 254 characters." ], "locale": [ "Choose sl, hr, en, sr-Cyrl or bs." ] } } }, "captchaError": { "summary": "captchaError", "description": "Complete verification and try again.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Complete verification and try again.", "instance": "/api/auth/forgot-password", "code": "captchaError", "traceId": "00-example-trace-id", "message": "Complete verification and try again.", "errors": { "turnstileToken": [ "Complete verification and try again." ] } } } } } } }, "413": { "description": "payloadTooLarge: Request too large", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "payloadTooLarge": { "summary": "payloadTooLarge", "description": "Request too large", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request too large", "status": 413, "detail": "Request too large", "instance": "/api/auth/forgot-password", "code": "payloadTooLarge", "traceId": "00-example-trace-id", "message": "Request too large" } } } } } }, "415": { "description": "unsupportedMediaType: Unsupported content type", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unsupportedMediaType": { "summary": "unsupportedMediaType", "description": "Unsupported content type", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Unsupported content type", "status": 415, "detail": "Unsupported content type", "instance": "/api/auth/forgot-password", "code": "unsupportedMediaType", "traceId": "00-example-trace-id", "message": "Unsupported content type" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/auth/forgot-password", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable; demoFormsDisabled: Forms are disabled in demo mode.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/auth/forgot-password", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } }, "demoFormsDisabled": { "summary": "demoFormsDisabled", "description": "Forms are disabled in demo mode.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Forms are disabled in demo mode.", "instance": "/api/auth/forgot-password", "code": "demoFormsDisabled", "traceId": "00-example-trace-id", "message": "Forms are disabled in demo mode." } } } } } } }, "security": [ ] } }, "/api/auth/reset-password": { "post": { "tags": [ "Account" ], "summary": "Set a new password and revoke sessions", "description": "Consume the one-hour, single-use reset token and replace the password. Revokes all access/refresh sessions and queues a password-change notification. Login again with the new password. Invalid, expired or reused tokens return 400.\n\nIP protection: 300 requests/minute globally, plus a shared 5/minute route policy. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### Reset password\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/auth/reset-password' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"token\": \"REPLACE_WITH_RESET_TOKEN\", \"password\": \"New-replacement-password-123!\", \"locale\": \"en\"}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/auth/reset-password\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({\"token\": \"REPLACE_WITH_RESET_TOKEN\", \"password\": \"New-replacement-password-123!\", \"locale\": \"en\"})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/auth/reset-password\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"token\": \"REPLACE_WITH_RESET_TOKEN\",\n \"password\": \"New-replacement-password-123!\",\n \"locale\": \"en\"\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Serbian recovery\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/auth/reset-password' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"token\": \"REPLACE_WITH_RESET_TOKEN\", \"password\": \"New-replacement-password-123!\", \"locale\": \"sr-Cyrl\"}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/auth/reset-password\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({\"token\": \"REPLACE_WITH_RESET_TOKEN\", \"password\": \"New-replacement-password-123!\", \"locale\": \"sr-Cyrl\"})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/auth/reset-password\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"token\": \"REPLACE_WITH_RESET_TOKEN\",\n \"password\": \"New-replacement-password-123!\",\n \"locale\": \"sr-Cyrl\"\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "ResetPassword", "requestBody": { "description": "Required token and password (12–128 characters); optional locale defaults to en.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetInput" }, "examples": { "Reset password": { "summary": "Reset password", "value": { "token": "REPLACE_WITH_RESET_TOKEN", "password": "New-replacement-password-123!", "locale": "en" } }, "Serbian recovery": { "summary": "Serbian recovery", "value": { "token": "REPLACE_WITH_RESET_TOKEN", "password": "New-replacement-password-123!", "locale": "sr-Cyrl" } } } } }, "required": true }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "required": [ "message" ], "type": "object", "properties": { "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." } } }, "examples": { "success": { "summary": "success", "value": { "message": "Password reset. You can now sign in." } } } } } }, "400": { "description": "validationError: Please check the information you entered.; confirmationInvalid: The link is invalid or expired.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/auth/reset-password", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "token": [ "Supply the email token, up to 128 characters." ], "password": [ "Use 12–128 password characters." ], "locale": [ "Choose sl, hr, en, sr-Cyrl or bs." ] } } }, "confirmationInvalid": { "summary": "confirmationInvalid", "description": "The link is invalid or expired.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "The link is invalid or expired.", "instance": "/api/auth/reset-password", "code": "confirmationInvalid", "traceId": "00-example-trace-id", "message": "The link is invalid or expired.", "errors": { "token": [ "The link is invalid or expired." ] } } } } } } }, "413": { "description": "payloadTooLarge: Request too large", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "payloadTooLarge": { "summary": "payloadTooLarge", "description": "Request too large", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request too large", "status": 413, "detail": "Request too large", "instance": "/api/auth/reset-password", "code": "payloadTooLarge", "traceId": "00-example-trace-id", "message": "Request too large" } } } } } }, "415": { "description": "unsupportedMediaType: Unsupported content type", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unsupportedMediaType": { "summary": "unsupportedMediaType", "description": "Unsupported content type", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Unsupported content type", "status": 415, "detail": "Unsupported content type", "instance": "/api/auth/reset-password", "code": "unsupportedMediaType", "traceId": "00-example-trace-id", "message": "Unsupported content type" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/auth/reset-password", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/auth/reset-password", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } }, "security": [ ] } }, "/api/auth/logout": { "post": { "tags": [ "Account" ], "summary": "Revoke the current session", "description": "Revoke this authenticated session and delete its browser refresh cookie. Both tokens for this session become unusable. Other sessions remain active. Requires a valid access token; refresh first if it has expired. Returns 204 with no body.\n\nIP protection: 300 requests/minute globally, plus a shared 5/minute route policy. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### Sign out\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/auth/logout' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/auth/logout\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/auth/logout\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Sign out after refresh\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/auth/logout' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/auth/logout\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/auth/logout\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "LogoutSession", "responses": { "204": { "description": "Session revoked. Empty response body.", "headers": { "Set-Cookie": { "description": "HttpOnly SameSite=Strict refresh cookie scoped to /api/auth; Secure on HTTPS. Logout clears it.", "schema": { "type": "string" } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/auth/logout", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/auth/logout", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/auth/logout", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } } } }, "/api/admin/support-sessions": { "post": { "tags": [ "Administration" ], "summary": "Work as subscriber", "description": "Actions and searches use the subscriber account and quota. Your administrator identity remains recorded. Access ends at 30 min\n\n### StartSupportSession\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\nusing var client = new HttpClient(new HttpClientHandler { UseCookies = true });\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/admin/support-sessions\");\nrequest.Headers.TryAddWithoutValidation(\"Origin\", \"http://localhost:5278\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer YOUR_ACCESS_TOKEN\");\nrequest.Content = new StringContent(\"{\\\"reason\\\":\\\"Requested subscriber assistance\\\",\\\"actionId\\\":\\\"091861f5-8532-4364-895e-331e496b67f1\\\",\\\"accountId\\\":\\\"3651acac-40a5-4d50-88c9-e3b312f4c72a\\\"}\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nresponse.EnsureSuccessStatusCode();\n// Keep the same HttpClient/CookieContainer for subsequent requests and stopping support.\n```\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/admin/support-sessions' --header 'Origin: http://localhost:5278' --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' --header 'Content-Type: application/json' --cookie cookies.txt --cookie-jar cookies.txt --data '{\"reason\":\"Requested subscriber assistance\",\"actionId\":\"091861f5-8532-4364-895e-331e496b67f1\",\"accountId\":\"3651acac-40a5-4d50-88c9-e3b312f4c72a\"}'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/admin/support-sessions\", {method:\"POST\", credentials:\"same-origin\", headers:{Authorization:\"Bearer \" + accessToken,\"Content-Type\":\"application/json\"},body:JSON.stringify({\"reason\":\"Requested subscriber assistance\",\"actionId\":\"091861f5-8532-4364-895e-331e496b67f1\",\"accountId\":\"3651acac-40a5-4d50-88c9-e3b312f4c72a\"})}); if(!response.ok) throw new Error(\"Support session request failed\");\n```", "operationId": "StartSupportSession", "parameters": [ { "name": "Origin", "in": "header", "description": "Exact service scheme and host, including local port. Required for CAPTCHA submissions and cookie-based refresh. Browser supplies it automatically.", "required": true, "schema": { "type": "string" }, "example": "http://localhost:5278" } ], "requestBody": { "description": "StartSupportSessionBody", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportInput" }, "examples": { "StartSupportSession": { "summary": "StartSupportSession", "value": { "reason": "Requested subscriber assistance", "actionId": "091861f5-8532-4364-895e-331e496b67f1", "accountId": "3651acac-40a5-4d50-88c9-e3b312f4c72a" } } } } }, "required": true }, "responses": { "201": { "description": "Support session created; HttpOnly cookie binds it to the current administrator login. No subscriber credentials are returned.", "content": { "application/json": { "schema": { "required": [ "id", "expiresAt", "accountId" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "expiresAt": { "type": "string" }, "accountId": { "type": "string" } } }, "example": { "id": "091861f5-8532-4364-895e-331e496b67f1", "expiresAt": "2026-11-01T12:30:00Z", "accountId": "3651acac-40a5-4d50-88c9-e3b312f4c72a" } } } }, "400": { "description": "validationError: Please check the information you entered.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/admin/support-sessions", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/admin/support-sessions", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "403": { "description": "forbidden: Access denied", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "forbidden": { "summary": "forbidden", "description": "Access denied", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Access denied", "status": 403, "detail": "Access denied", "instance": "/api/admin/support-sessions", "code": "forbidden", "traceId": "00-example-trace-id", "message": "Access denied" } } } } } }, "409": { "description": "orderConflict: Order data conflicts with the saved order/event. Retry the original details.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "orderConflict": { "summary": "orderConflict", "description": "Order data conflicts with the saved order/event. Retry the original details.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request conflict", "status": 409, "detail": "Order data conflicts with the saved order/event. Retry the original details.", "instance": "/api/admin/support-sessions", "code": "orderConflict", "traceId": "00-example-trace-id", "message": "Order data conflicts with the saved order/event. Retry the original details." } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/admin/support-sessions", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/admin/support-sessions", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } } } }, "/api/admin/users": { "get": { "tags": [ "Administration" ], "summary": "User administration", "description": "Review registered users and assign packages. Manual assignments take priority over automatic activation. Superadmin access is required.\n\n### all\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/admin/users?page=0&filter=all' \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/admin/users?page=0&filter=all\", {\"method\": \"GET\", \"headers\": {\"Content-Type\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}});\nif (!response.ok) throw new Error(await response.text());\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/admin/users?page=0&filter=all\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```\n\n### unconfirmed\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/admin/users?page=0&filter=unconfirmed' \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/admin/users?page=0&filter=unconfirmed\", {\"method\": \"GET\", \"headers\": {\"Content-Type\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}});\nif (!response.ok) throw new Error(await response.text());\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/admin/users?page=0&filter=unconfirmed\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```\n\n### paid\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/admin/users?page=0&filter=paid' \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/admin/users?page=0&filter=paid\", {\"method\": \"GET\", \"headers\": {\"Content-Type\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}});\nif (!response.ok) throw new Error(await response.text());\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/admin/users?page=0&filter=paid\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```\n\n### bank\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/admin/users?page=0&filter=bank' \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/admin/users?page=0&filter=bank\", {\"method\": \"GET\", \"headers\": {\"Content-Type\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}});\nif (!response.ok) throw new Error(await response.text());\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/admin/users?page=0&filter=bank\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```\n\n### active\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/admin/users?page=0&filter=active' \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/admin/users?page=0&filter=active\", {\"method\": \"GET\", \"headers\": {\"Content-Type\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}});\nif (!response.ok) throw new Error(await response.text());\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/admin/users?page=0&filter=active\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```", "operationId": "AdminUsers", "parameters": [ { "name": "page", "in": "query", "description": "Next", "schema": { "type": "integer", "format": "int32" } }, { "name": "q", "in": "query", "description": "Required company-name prefix, 2–120 normalized Unicode characters; at most 12 results. Cyrillic remains Cyrillic.", "schema": { "maxLength": 200, "minLength": 0, "type": "string" }, "example": "Pr" }, { "name": "filter", "in": "query", "description": "Show", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Up to 50 registered users; password and token fields are never included.", "content": { "application/json": { "schema": { "type": "array", "items": { "required": [ "id", "email", "name", "confirmed", "disabled", "plan", "planExpires", "isSuperadmin", "manualPlan", "hasPaid", "awaitingTransfer", "billing", "invoicePending" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "email": { "type": "string", "description": "Authenticated account email." }, "name": { "type": "string", "description": "Company legal name or account display name, depending on response." }, "confirmed": { "type": "boolean" }, "disabled": { "type": "boolean" }, "plan": { "type": "string", "description": "Effective account plan or purchased plan identifier." }, "planExpires": { "type": "string", "nullable": true }, "isSuperadmin": { "type": "boolean" }, "manualPlan": { "type": "boolean" }, "hasPaid": { "type": "boolean" }, "awaitingTransfer": { "type": "boolean" }, "billing": { "required": [ "customerType", "billingName", "street", "postalCode", "city", "countryCode", "taxNumber", "vatStatus" ], "type": "object", "properties": { "customerType": { "type": "string" }, "billingName": { "type": "string" }, "street": { "type": "string" }, "postalCode": { "type": "string", "description": "Separately supplied postal code; empty if unavailable." }, "city": { "type": "string", "description": "Separately supplied locality; empty if unavailable." }, "countryCode": { "type": "string" }, "taxNumber": { "type": "string", "description": "Tax/VAT identifier when supplied by the registry; empty if unavailable." }, "vatStatus": { "type": "string" } } }, "invoicePending": { "type": "boolean" } } } }, "example": [ { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "email": "user@example.invalid", "name": "Example", "confirmed": true, "disabled": false, "plan": "free", "planExpires": null, "isSuperadmin": false, "manualPlan": false, "hasPaid": false, "awaitingTransfer": false, "billing": { "customerType": "individual", "billingName": "Example User", "street": "", "postalCode": "1000", "city": "Ljubljana", "countryCode": "SI", "taxNumber": "", "vatStatus": "none" }, "invoicePending": false } ] } } }, "400": { "description": "validationError: Please check the information you entered.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/admin/users", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "request": [ "Please check the information you entered." ] } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/admin/users", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "403": { "description": "forbidden: Access denied", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "forbidden": { "summary": "forbidden", "description": "Access denied", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Access denied", "status": 403, "detail": "Access denied", "instance": "/api/admin/users", "code": "forbidden", "traceId": "00-example-trace-id", "message": "Access denied" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/admin/users", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/admin/users", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } } } }, "/api/admin/users/{id}/bank-orders": { "get": { "tags": [ "Administration" ], "summary": "Review transfers", "description": "Review transfers. I checked the bank statement and confirm receipt of the full amount.\n\n### pending_transfers\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/admin/users/8b0b3211-701a-4f36-88be-d522f61e7e45/bank-orders' \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/admin/users/8b0b3211-701a-4f36-88be-d522f61e7e45/bank-orders\", {\"method\": \"GET\", \"headers\": {\"Content-Type\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}});\nif (!response.ok) throw new Error(await response.text());\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/admin/users/8b0b3211-701a-4f36-88be-d522f61e7e45/bank-orders\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```", "operationId": "AdminBankOrders", "parameters": [ { "name": "id", "in": "path", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "8b0b3211-701a-4f36-88be-d522f61e7e45" } ], "responses": { "200": { "description": "Up to 50 unpaid PROD bank orders belonging to the selected account.", "content": { "application/json": { "schema": { "type": "array", "items": { "required": [ "id", "accountId", "plan", "method", "amountMinor", "currency", "environment", "billingName", "billingAddress", "billingVatId", "periodDays", "paymentId", "status", "grantedAt" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "accountId": { "type": "string" }, "plan": { "type": "string", "description": "Effective account plan or purchased plan identifier." }, "method": { "type": "string" }, "amountMinor": { "type": "integer" }, "currency": { "type": "string", "description": "EUR." }, "environment": { "type": "string", "description": "TEST or PROD. TEST never grants a real subscription." }, "billingName": { "type": "string" }, "billingAddress": { "type": "string" }, "billingVatId": { "type": "string" }, "periodDays": { "type": "integer", "description": "Saved subscription period, currently 30 days." }, "paymentId": { "type": "string", "description": "Gateway payment UUID, null before attachment.", "format": "uuid", "nullable": true }, "status": { "type": "string", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "grantedAt": { "type": "string", "description": "Grant timestamp, null until a real paid entitlement is granted.", "format": "date-time", "nullable": true } } } }, "example": [ { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "accountId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "method": "bank", "amountMinor": 1219, "currency": "EUR", "environment": "PROD", "billingName": "Example", "billingAddress": "Ljubljana", "billingVatId": "", "periodDays": 30, "paymentId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "status": "AwaitingTransfer", "grantedAt": null } ] } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/admin/users/{id:guid}/bank-orders", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "403": { "description": "forbidden: Access denied", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "forbidden": { "summary": "forbidden", "description": "Access denied", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Access denied", "status": 403, "detail": "Access denied", "instance": "/api/admin/users/{id:guid}/bank-orders", "code": "forbidden", "traceId": "00-example-trace-id", "message": "Access denied" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/admin/users/{id:guid}/bank-orders", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/admin/users/{id:guid}/bank-orders", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } } } }, "/api/admin/bank-orders/{id}/confirm": { "post": { "tags": [ "Administration" ], "summary": "Confirm payment and activate plan", "description": "I checked the bank statement and confirm receipt of the full amount. Payment confirmed and plan activated. Invoice preparation has been recorded.\n\n### confirm\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/admin/bank-orders/8b0b3211-701a-4f36-88be-d522f61e7e45/confirm' \\\n --header 'Content-Type: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN' \\\n --data-raw '{\"actionId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"amountMinor\": 1219, \"reference\": \"BANK-STATEMENT-2026-00001\"}'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/admin/bank-orders/8b0b3211-701a-4f36-88be-d522f61e7e45/confirm\", {\"method\": \"POST\", \"headers\": {\"Content-Type\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}, \"body\": \"{\\\"actionId\\\": \\\"8b0b3211-701a-4f36-88be-d522f61e7e45\\\", \\\"amountMinor\\\": 1219, \\\"reference\\\": \\\"BANK-STATEMENT-2026-00001\\\"}\"});\nif (!response.ok) throw new Error(await response.text());\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/admin/bank-orders/8b0b3211-701a-4f36-88be-d522f61e7e45/confirm\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nrequest.Content = new StringContent(\"{\\\"actionId\\\": \\\"8b0b3211-701a-4f36-88be-d522f61e7e45\\\", \\\"amountMinor\\\": 1219, \\\"reference\\\": \\\"BANK-STATEMENT-2026-00001\\\"}\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```", "operationId": "AdminConfirmBank", "parameters": [ { "name": "id", "in": "path", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "8b0b3211-701a-4f36-88be-d522f61e7e45" } ], "requestBody": { "description": "actionId: UUID; amountMinor: EUR × 100; reference: Unique transaction identifier from bank statement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankConfirmationInput" }, "examples": { "confirm": { "summary": "confirm", "value": { "actionId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "amountMinor": 1219, "reference": "BANK-STATEMENT-2026-00001" } } } } }, "required": true }, "responses": { "204": { "description": "Payment audited, plan activated once, confirmation email and invoice preparation queued atomically. Repeating the same action and payload is safe. No PDF is promised by this response." }, "400": { "description": "validationError: Please check the information you entered.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/admin/bank-orders/{id:guid}/confirm", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "request": [ "Please check the information you entered." ] } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/admin/bank-orders/{id:guid}/confirm", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "403": { "description": "forbidden: Access denied", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "forbidden": { "summary": "forbidden", "description": "Access denied", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Access denied", "status": 403, "detail": "Access denied", "instance": "/api/admin/bank-orders/{id:guid}/confirm", "code": "forbidden", "traceId": "00-example-trace-id", "message": "Access denied" } } } } } }, "409": { "description": "orderConflict: Order data conflicts with the saved order/event. Retry the original details.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "orderConflict": { "summary": "orderConflict", "description": "Order data conflicts with the saved order/event. Retry the original details.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request conflict", "status": 409, "detail": "Order data conflicts with the saved order/event. Retry the original details.", "instance": "/api/admin/bank-orders/{id:guid}/confirm", "code": "orderConflict", "traceId": "00-example-trace-id", "message": "Order data conflicts with the saved order/event. Retry the original details." } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/admin/bank-orders/{id:guid}/confirm", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/admin/bank-orders/{id:guid}/confirm", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } } } }, "/api/admin/users/{id}/plan": { "put": { "tags": [ "Administration" ], "summary": "Save package", "description": "Review registered users and assign packages. Manual assignments take priority over automatic activation. Choose a future expiry date for a paid package; leave it empty for Free.\n\n### free\n\n**cURL**\n\n```bash\ncurl --request PUT 'http://localhost:5278/api/admin/users/8b0b3211-701a-4f36-88be-d522f61e7e45/plan' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data '{\"actionId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"plan\": \"free\", \"expiresAt\": null, \"reason\": \"Manual assignment requested by account owner\"}'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/admin/users/8b0b3211-701a-4f36-88be-d522f61e7e45/plan\", {\"method\": \"PUT\", \"headers\": {\"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\", \"Content-Type\": \"application/json\"}, \"body\": \"{\\\"actionId\\\": \\\"8b0b3211-701a-4f36-88be-d522f61e7e45\\\", \\\"plan\\\": \\\"free\\\", \\\"expiresAt\\\": null, \\\"reason\\\": \\\"Manual assignment requested by account owner\\\"}\"});\nif (!response.ok) throw new Error(await response.text());\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Put, \"http://localhost:5278/api/admin/users/8b0b3211-701a-4f36-88be-d522f61e7e45/plan\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nrequest.Content = new StringContent(\"{\\\"actionId\\\": \\\"8b0b3211-701a-4f36-88be-d522f61e7e45\\\", \\\"plan\\\": \\\"free\\\", \\\"expiresAt\\\": null, \\\"reason\\\": \\\"Manual assignment requested by account owner\\\"}\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine($\"{(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}\");\n```\n\n### start\n\n**cURL**\n\n```bash\ncurl --request PUT 'http://localhost:5278/api/admin/users/8b0b3211-701a-4f36-88be-d522f61e7e45/plan' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data '{\"actionId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"plan\": \"start\", \"expiresAt\": \"2027-12-31T23:59:59Z\", \"reason\": \"Manual assignment requested by account owner\"}'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/admin/users/8b0b3211-701a-4f36-88be-d522f61e7e45/plan\", {\"method\": \"PUT\", \"headers\": {\"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\", \"Content-Type\": \"application/json\"}, \"body\": \"{\\\"actionId\\\": \\\"8b0b3211-701a-4f36-88be-d522f61e7e45\\\", \\\"plan\\\": \\\"start\\\", \\\"expiresAt\\\": \\\"2027-12-31T23:59:59Z\\\", \\\"reason\\\": \\\"Manual assignment requested by account owner\\\"}\"});\nif (!response.ok) throw new Error(await response.text());\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Put, \"http://localhost:5278/api/admin/users/8b0b3211-701a-4f36-88be-d522f61e7e45/plan\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nrequest.Content = new StringContent(\"{\\\"actionId\\\": \\\"8b0b3211-701a-4f36-88be-d522f61e7e45\\\", \\\"plan\\\": \\\"start\\\", \\\"expiresAt\\\": \\\"2027-12-31T23:59:59Z\\\", \\\"reason\\\": \\\"Manual assignment requested by account owner\\\"}\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine($\"{(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}\");\n```\n\n### pro\n\n**cURL**\n\n```bash\ncurl --request PUT 'http://localhost:5278/api/admin/users/8b0b3211-701a-4f36-88be-d522f61e7e45/plan' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data '{\"actionId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"plan\": \"pro\", \"expiresAt\": \"2027-12-31T23:59:59Z\", \"reason\": \"Manual assignment requested by account owner\"}'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/admin/users/8b0b3211-701a-4f36-88be-d522f61e7e45/plan\", {\"method\": \"PUT\", \"headers\": {\"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\", \"Content-Type\": \"application/json\"}, \"body\": \"{\\\"actionId\\\": \\\"8b0b3211-701a-4f36-88be-d522f61e7e45\\\", \\\"plan\\\": \\\"pro\\\", \\\"expiresAt\\\": \\\"2027-12-31T23:59:59Z\\\", \\\"reason\\\": \\\"Manual assignment requested by account owner\\\"}\"});\nif (!response.ok) throw new Error(await response.text());\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Put, \"http://localhost:5278/api/admin/users/8b0b3211-701a-4f36-88be-d522f61e7e45/plan\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nrequest.Content = new StringContent(\"{\\\"actionId\\\": \\\"8b0b3211-701a-4f36-88be-d522f61e7e45\\\", \\\"plan\\\": \\\"pro\\\", \\\"expiresAt\\\": \\\"2027-12-31T23:59:59Z\\\", \\\"reason\\\": \\\"Manual assignment requested by account owner\\\"}\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine($\"{(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}\");\n```", "operationId": "AdminSetPlan", "parameters": [ { "name": "id", "in": "path", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "8b0b3211-701a-4f36-88be-d522f61e7e45" } ], "requestBody": { "description": "Choose a future expiry date for a paid package; leave it empty for Free. Enter a reason, up to 500 characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPlanInput" }, "examples": { "free": { "summary": "free", "value": { "actionId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "free", "expiresAt": null, "reason": "Manual assignment requested by account owner" } }, "start": { "summary": "start", "value": { "actionId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "expiresAt": "2027-12-31T23:59:59Z", "reason": "Manual assignment requested by account owner" } }, "pro": { "summary": "pro", "value": { "actionId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "pro", "expiresAt": "2027-12-31T23:59:59Z", "reason": "Manual assignment requested by account owner" } } } } }, "required": true }, "responses": { "204": { "description": "Manual plan saved and audit entry recorded; no response body." }, "400": { "description": "validationError: Please check the information you entered.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/admin/users/{id:guid}/plan", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "request": [ "Please check the information you entered." ] } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/admin/users/{id:guid}/plan", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "403": { "description": "forbidden: Access denied", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "forbidden": { "summary": "forbidden", "description": "Access denied", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Access denied", "status": 403, "detail": "Access denied", "instance": "/api/admin/users/{id:guid}/plan", "code": "forbidden", "traceId": "00-example-trace-id", "message": "Access denied" } } } } } }, "409": { "description": "orderConflict: Order data conflicts with the saved order/event. Retry the original details.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "orderConflict": { "summary": "orderConflict", "description": "Order data conflicts with the saved order/event. Retry the original details.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request conflict", "status": 409, "detail": "Order data conflicts with the saved order/event. Retry the original details.", "instance": "/api/admin/users/{id:guid}/plan", "code": "orderConflict", "traceId": "00-example-trace-id", "message": "Order data conflicts with the saved order/event. Retry the original details." } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/admin/users/{id:guid}/plan", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/admin/users/{id:guid}/plan", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } } } }, "/api/billing/orders": { "post": { "tags": [ "Billing" ], "summary": "Create or retry a payment order", "description": "Create an immutable account-owned 30-day order with server-configured EUR pricing. Sample amount 12.34 is illustrative, not a published price. Retry the same UUID and identical fields. Active cross-plan switches return 409 before checkout. Requires gateway configuration and price; PROD also requires ProductionBillingReady. TEST never grants a real plan. Bank instructions do not mean receipt. Matching Paid evidence grants once. A gateway timeout can occur after acceptance: retry the SAME ID or read status; never create a replacement order.\n\nIP protection: 300 requests/minute globally, plus a shared 5/minute route policy. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### Stripe checkout\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/billing/orders' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"plan\": \"start\", \"method\": \"stripe\", \"billingName\": \"Example Company\", \"billingAddress\": \"Example street 1, 1000 Ljubljana\", \"billingVatId\": null}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/billing/orders\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"plan\": \"start\", \"method\": \"stripe\", \"billingName\": \"Example Company\", \"billingAddress\": \"Example street 1, 1000 Ljubljana\", \"billingVatId\": null})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/billing/orders\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\",\n \"plan\": \"start\",\n \"method\": \"stripe\",\n \"billingName\": \"Example Company\",\n \"billingAddress\": \"Example street 1, 1000 Ljubljana\",\n \"billingVatId\": null\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### PayPal checkout\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/billing/orders' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"plan\": \"start\", \"method\": \"paypal\", \"billingName\": \"Example Company\", \"billingAddress\": \"Example street 1, 1000 Ljubljana\", \"billingVatId\": null}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/billing/orders\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"plan\": \"start\", \"method\": \"paypal\", \"billingName\": \"Example Company\", \"billingAddress\": \"Example street 1, 1000 Ljubljana\", \"billingVatId\": null})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/billing/orders\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\",\n \"plan\": \"start\",\n \"method\": \"paypal\",\n \"billingName\": \"Example Company\",\n \"billingAddress\": \"Example street 1, 1000 Ljubljana\",\n \"billingVatId\": null\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Bank transfer instructions\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/billing/orders' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"plan\": \"start\", \"method\": \"bank\", \"billingName\": \"Example Company\", \"billingAddress\": \"Example street 1, 1000 Ljubljana\", \"billingVatId\": null}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/billing/orders\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"plan\": \"start\", \"method\": \"bank\", \"billingName\": \"Example Company\", \"billingAddress\": \"Example street 1, 1000 Ljubljana\", \"billingVatId\": null})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/billing/orders\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\",\n \"plan\": \"start\",\n \"method\": \"bank\",\n \"billingName\": \"Example Company\",\n \"billingAddress\": \"Example street 1, 1000 Ljubljana\",\n \"billingVatId\": null\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "CreateBillingOrder", "requestBody": { "description": "Required id, plan, method, billingName and billingAddress; billingVatId optional. Do not send amount/currency: server chooses these.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingOrderInput" }, "examples": { "Stripe checkout": { "summary": "Stripe checkout", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "method": "stripe", "billingName": "Example Company", "billingAddress": "Example street 1, 1000 Ljubljana", "billingVatId": null } }, "PayPal checkout": { "summary": "PayPal checkout", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "method": "paypal", "billingName": "Example Company", "billingAddress": "Example street 1, 1000 Ljubljana", "billingVatId": null } }, "Bank transfer instructions": { "summary": "Bank transfer instructions", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "method": "bank", "billingName": "Example Company", "billingAddress": "Example street 1, 1000 Ljubljana", "billingVatId": null } } } } }, "required": true }, "responses": { "202": { "description": "Accepted order; inspect status. Does not imply paid or activated.", "headers": { "Location": { "description": "Relative URL of the saved order status endpoint.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "required": [ "id", "plan", "method", "amount", "currency", "environment", "status", "periodDays", "paymentId", "grantedAt", "result" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "plan": { "type": "string", "description": "Effective account plan or purchased plan identifier." }, "method": { "type": "string" }, "amount": { "type": "number", "description": "Order amount in EUR major units; illustrative examples are not prices." }, "currency": { "type": "string", "description": "EUR." }, "environment": { "type": "string", "description": "TEST or PROD. TEST never grants a real subscription." }, "status": { "type": "string", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "periodDays": { "type": "integer", "description": "Saved subscription period, currently 30 days." }, "paymentId": { "type": "string", "description": "Gateway payment UUID, null before attachment.", "format": "uuid", "nullable": true }, "grantedAt": { "type": "string", "description": "Grant timestamp, null until a real paid entitlement is granted.", "format": "date-time", "nullable": true }, "result": { "type": "object", "properties": { "paymentState": { "type": "string" }, "checkoutUrl": { "type": "string", "format": "uri" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "payee": { "type": "string" }, "iban": { "type": "string" }, "bic": { "type": "string" } }, "description": "Optional whitelisted gateway fields. Missing/null while no result is available. checkoutUrl only uses approved Stripe/PayPal HTTPS hosts.", "nullable": true } } }, "examples": { "success": { "summary": "success", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "method": "stripe", "amount": 12.34, "currency": "EUR", "environment": "TEST", "status": "Created", "periodDays": 30, "paymentId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "grantedAt": null, "result": { "paymentState": "Pending", "checkoutUrl": "https://checkout.stripe.com/REPLACE_WITH_PROVIDER_SESSION" } } }, "bankPending": { "summary": "bankPending", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "method": "bank", "amount": 12.34, "currency": "EUR", "environment": "TEST", "status": "AwaitingTransfer", "periodDays": 30, "paymentId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "grantedAt": null, "result": { "paymentState": "AwaitingTransfer", "currency": "EUR" } } }, "testPayment": { "summary": "testPayment", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "method": "stripe", "amount": 12.34, "currency": "EUR", "environment": "TEST", "status": "TestPaid", "periodDays": 30, "paymentId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "grantedAt": null, "result": { "paymentState": "Paid", "amount": 12.34, "currency": "EUR" } } } } } } }, "400": { "description": "validationError: Please check the information you entered.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/billing/orders", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "id": [ "Supply a non-empty UUID." ], "plan": [ "Choose start or pro." ], "method": [ "Choose stripe, paypal or bank." ], "billingName": [ "Enter a name of 1–200 characters." ], "billingAddress": [ "Enter a billing address of 1–1,000 characters." ], "billingVatId": [ "VAT ID may contain at most 100 characters." ] } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/billing/orders", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "409": { "description": "orderConflict: Order data conflicts with the saved order/event. Retry the original details.; planSwitchUnavailable: Renew the same active plan or wait for expiry; switching at checkout is unavailable.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "orderConflict": { "summary": "orderConflict", "description": "Order data conflicts with the saved order/event. Retry the original details.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request conflict", "status": 409, "detail": "Order data conflicts with the saved order/event. Retry the original details.", "instance": "/api/billing/orders", "code": "orderConflict", "traceId": "00-example-trace-id", "message": "Order data conflicts with the saved order/event. Retry the original details." } }, "planSwitchUnavailable": { "summary": "planSwitchUnavailable", "description": "Renew the same active plan or wait for expiry; switching at checkout is unavailable.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request conflict", "status": 409, "detail": "Renew the same active plan or wait for expiry; switching at checkout is unavailable.", "instance": "/api/billing/orders", "code": "planSwitchUnavailable", "traceId": "00-example-trace-id", "message": "Renew the same active plan or wait for expiry; switching at checkout is unavailable." } } } } } }, "413": { "description": "payloadTooLarge: Request too large", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "payloadTooLarge": { "summary": "payloadTooLarge", "description": "Request too large", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request too large", "status": 413, "detail": "Request too large", "instance": "/api/billing/orders", "code": "payloadTooLarge", "traceId": "00-example-trace-id", "message": "Request too large" } } } } } }, "415": { "description": "unsupportedMediaType: Unsupported content type", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unsupportedMediaType": { "summary": "unsupportedMediaType", "description": "Unsupported content type", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Unsupported content type", "status": 415, "detail": "Unsupported content type", "instance": "/api/billing/orders", "code": "unsupportedMediaType", "traceId": "00-example-trace-id", "message": "Unsupported content type" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/billing/orders", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable; paymentsUnavailable: Checkout is disabled or incompletely configured.; quoteRequired: No price is configured; request a quotation.; paymentPending: Status is uncertain. Retry the same order ID; do not create a replacement order.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/billing/orders", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } }, "paymentsUnavailable": { "summary": "paymentsUnavailable", "description": "Checkout is disabled or incompletely configured.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Checkout is disabled or incompletely configured.", "instance": "/api/billing/orders", "code": "paymentsUnavailable", "traceId": "00-example-trace-id", "message": "Checkout is disabled or incompletely configured." } }, "quoteRequired": { "summary": "quoteRequired", "description": "No price is configured; request a quotation.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "No price is configured; request a quotation.", "instance": "/api/billing/orders", "code": "quoteRequired", "traceId": "00-example-trace-id", "message": "No price is configured; request a quotation." } }, "paymentPending": { "summary": "paymentPending", "description": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "instance": "/api/billing/orders", "code": "paymentPending", "traceId": "00-example-trace-id", "message": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "orderId": "8b0b3211-701a-4f36-88be-d522f61e7e45" } } } } } } } } }, "/api/billing/orders/{id}": { "get": { "tags": [ "Billing" ], "summary": "Read and reconcile your payment order", "description": "Only the owner may read an order; another account receives 404. May reconcile gateway status and atomically grant an eligible period. Provider polling is throttled to once per order every three seconds; faster reads return stored state. Disabled gateway returns stored order. TEST yields TestPaid only. AwaitingTransfer is pending bank receipt. NeedsAttention requires operator review. Browser redirects cannot activate plans.\n\nIP protection: 300 requests/minute globally, plus a shared 120/minute route policy. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### Read order\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/billing/orders/8b0b3211-701a-4f36-88be-d522f61e7e45' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/billing/orders/8b0b3211-701a-4f36-88be-d522f61e7e45\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/billing/orders/8b0b3211-701a-4f36-88be-d522f61e7e45\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Read another owned order\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/billing/orders/6d4f7638-8db2-42b7-8b9b-08a1c019ed50' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/billing/orders/6d4f7638-8db2-42b7-8b9b-08a1c019ed50\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/billing/orders/6d4f7638-8db2-42b7-8b9b-08a1c019ed50\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "GetBillingOrder", "parameters": [ { "name": "id", "in": "path", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "8b0b3211-701a-4f36-88be-d522f61e7e45" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "required": [ "id", "plan", "method", "amount", "currency", "environment", "status", "periodDays", "paymentId", "grantedAt", "result" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "plan": { "type": "string", "description": "Effective account plan or purchased plan identifier." }, "method": { "type": "string" }, "amount": { "type": "number", "description": "Order amount in EUR major units; illustrative examples are not prices." }, "currency": { "type": "string", "description": "EUR." }, "environment": { "type": "string", "description": "TEST or PROD. TEST never grants a real subscription." }, "status": { "type": "string", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "periodDays": { "type": "integer", "description": "Saved subscription period, currently 30 days." }, "paymentId": { "type": "string", "description": "Gateway payment UUID, null before attachment.", "format": "uuid", "nullable": true }, "grantedAt": { "type": "string", "description": "Grant timestamp, null until a real paid entitlement is granted.", "format": "date-time", "nullable": true }, "result": { "type": "object", "properties": { "paymentState": { "type": "string" }, "checkoutUrl": { "type": "string", "format": "uri" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "payee": { "type": "string" }, "iban": { "type": "string" }, "bic": { "type": "string" } }, "description": "Optional whitelisted gateway fields. Missing/null while no result is available. checkoutUrl only uses approved Stripe/PayPal HTTPS hosts.", "nullable": true } } }, "examples": { "success": { "summary": "success", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "method": "stripe", "amount": 12.34, "currency": "EUR", "environment": "TEST", "status": "Created", "periodDays": 30, "paymentId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "grantedAt": null, "result": { "paymentState": "Pending", "checkoutUrl": "https://checkout.stripe.com/REPLACE_WITH_PROVIDER_SESSION" } } }, "bankPending": { "summary": "bankPending", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "method": "bank", "amount": 12.34, "currency": "EUR", "environment": "TEST", "status": "AwaitingTransfer", "periodDays": 30, "paymentId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "grantedAt": null, "result": { "paymentState": "AwaitingTransfer", "currency": "EUR" } } }, "testPayment": { "summary": "testPayment", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "method": "stripe", "amount": 12.34, "currency": "EUR", "environment": "TEST", "status": "TestPaid", "periodDays": 30, "paymentId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "grantedAt": null, "result": { "paymentState": "Paid", "amount": 12.34, "currency": "EUR" } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/billing/orders/{id:guid}", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "404": { "description": "notFound: Resource not found", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "notFound": { "summary": "notFound", "description": "Resource not found", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Resource not found", "status": 404, "detail": "Resource not found", "instance": "/api/billing/orders/{id:guid}", "code": "notFound", "traceId": "00-example-trace-id", "message": "Resource not found" } } } } } }, "409": { "description": "orderConflict: Order data conflicts with the saved order/event. Retry the original details.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "orderConflict": { "summary": "orderConflict", "description": "Order data conflicts with the saved order/event. Retry the original details.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request conflict", "status": 409, "detail": "Order data conflicts with the saved order/event. Retry the original details.", "instance": "/api/billing/orders/{id:guid}", "code": "orderConflict", "traceId": "00-example-trace-id", "message": "Order data conflicts with the saved order/event. Retry the original details." } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/billing/orders/{id:guid}", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable; paymentPending: Status is uncertain. Retry the same order ID; do not create a replacement order.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/billing/orders/{id:guid}", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } }, "paymentPending": { "summary": "paymentPending", "description": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "instance": "/api/billing/orders/{id:guid}", "code": "paymentPending", "traceId": "00-example-trace-id", "message": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "orderId": "8b0b3211-701a-4f36-88be-d522f61e7e45" } } } } } } } } }, "/api/billing/webhook": { "post": { "tags": [ "Billing" ], "summary": "Receive a signed payment gateway event", "description": "Gateway-to-server integration, not a customer checkout call. Validates exact-body HMAC, timestamp, endpoint, organization/project and test/live scope before recording the receipt. Fetches authoritative status from Pay; an event alone cannot grant access. Identical retries are safe. An event racing order attachment returns 503 for retry. Maximum raw body 65,536 bytes. Replace all IDs and compute a real signature; unchanged samples return 401. Never expose the signing key in a browser.\n\nIP protection: 300 requests/minute globally, plus a shared 120/minute route policy. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### TEST event envelope\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/billing/webhook' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --header 'Kvadrati-Signature: REPLACE_WITH_VALID_SIGNATURE' \\\n --header 'Kvadrati-Event-Id: 8b0b3211-701a-4f36-88be-d522f61e7e45' \\\n --header 'Kvadrati-Endpoint-Id: REPLACE_WITH_ENDPOINT_UUID' \\\n --data-raw '{\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"type\": \"payment.updated\", \"schemaVersion\": 1, \"createdAt\": \"2026-10-22T12:00:00Z\", \"environment\": \"test\", \"organizationId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"projectId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"resourceId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"data\": {\"paymentId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\"}}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\n// Server-only gateway illustration: compute a real signature over exact body bytes.\nconst response = await fetch(\"/api/billing/webhook\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Content-Type\": \"application/json\", \"Kvadrati-Signature\": \"REPLACE_WITH_VALID_SIGNATURE\", \"Kvadrati-Event-Id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"Kvadrati-Endpoint-Id\": \"REPLACE_WITH_ENDPOINT_UUID\"},\n body: JSON.stringify({\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"type\": \"payment.updated\", \"schemaVersion\": 1, \"createdAt\": \"2026-10-22T12:00:00Z\", \"environment\": \"test\", \"organizationId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"projectId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"resourceId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"data\": {\"paymentId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\"}})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/billing/webhook\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Kvadrati-Signature\", \"REPLACE_WITH_VALID_SIGNATURE\");\nrequest.Headers.TryAddWithoutValidation(\"Kvadrati-Event-Id\", \"8b0b3211-701a-4f36-88be-d522f61e7e45\");\nrequest.Headers.TryAddWithoutValidation(\"Kvadrati-Endpoint-Id\", \"REPLACE_WITH_ENDPOINT_UUID\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\",\n \"type\": \"payment.updated\",\n \"schemaVersion\": 1,\n \"createdAt\": \"2026-10-22T12:00:00Z\",\n \"environment\": \"test\",\n \"organizationId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\",\n \"projectId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\",\n \"resourceId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\",\n \"data\": {\n \"paymentId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\"\n }\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Live envelope (requires live signing setup)\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/billing/webhook' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json' \\\n --header 'Kvadrati-Signature: REPLACE_WITH_VALID_SIGNATURE' \\\n --header 'Kvadrati-Event-Id: 8b0b3211-701a-4f36-88be-d522f61e7e45' \\\n --header 'Kvadrati-Endpoint-Id: REPLACE_WITH_ENDPOINT_UUID' \\\n --data-raw '{\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"type\": \"payment.updated\", \"schemaVersion\": 1, \"createdAt\": \"2026-10-22T12:00:00Z\", \"environment\": \"live\", \"organizationId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"projectId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"resourceId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"data\": {\"paymentId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\"}}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\n// Server-only gateway illustration: compute a real signature over exact body bytes.\nconst response = await fetch(\"/api/billing/webhook\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Content-Type\": \"application/json\", \"Kvadrati-Signature\": \"REPLACE_WITH_VALID_SIGNATURE\", \"Kvadrati-Event-Id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"Kvadrati-Endpoint-Id\": \"REPLACE_WITH_ENDPOINT_UUID\"},\n body: JSON.stringify({\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"type\": \"payment.updated\", \"schemaVersion\": 1, \"createdAt\": \"2026-10-22T12:00:00Z\", \"environment\": \"live\", \"organizationId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"projectId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"resourceId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"data\": {\"paymentId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\"}})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/billing/webhook\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Kvadrati-Signature\", \"REPLACE_WITH_VALID_SIGNATURE\");\nrequest.Headers.TryAddWithoutValidation(\"Kvadrati-Event-Id\", \"8b0b3211-701a-4f36-88be-d522f61e7e45\");\nrequest.Headers.TryAddWithoutValidation(\"Kvadrati-Endpoint-Id\", \"REPLACE_WITH_ENDPOINT_UUID\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\",\n \"type\": \"payment.updated\",\n \"schemaVersion\": 1,\n \"createdAt\": \"2026-10-22T12:00:00Z\",\n \"environment\": \"live\",\n \"organizationId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\",\n \"projectId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\",\n \"resourceId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\",\n \"data\": {\n \"paymentId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\"\n }\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "ReceivePaymentEvent", "parameters": [ { "name": "Kvadrati-Signature", "in": "header", "description": "Gateway HMAC: v=1;kid=;t=;h=. Sign exact raw UTF-8 bytes with the configured gateway protocol.", "required": true, "schema": { "type": "string" } }, { "name": "Kvadrati-Event-Id", "in": "header", "description": "Event UUID matching the signed envelope. Identical retries reuse the same ID.", "required": true, "schema": { "type": "string" } }, { "name": "Kvadrati-Endpoint-Id", "in": "header", "description": "Configured webhook endpoint UUID; included in the signature scope.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Raw signed JSON envelope plus three signature headers. Do not reformat JSON after signing.", "content": { "application/json": { "schema": { "required": [ "id", "type", "schemaVersion", "createdAt", "environment", "organizationId", "projectId", "resourceId", "data" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "type": { "type": "string" }, "schemaVersion": { "type": "integer" }, "createdAt": { "type": "string" }, "environment": { "type": "string", "description": "TEST or PROD. TEST never grants a real subscription." }, "organizationId": { "type": "string" }, "projectId": { "type": "string" }, "resourceId": { "type": "string" }, "data": { "required": [ "paymentId" ], "type": "object", "properties": { "paymentId": { "type": "string", "description": "Gateway payment UUID, null before attachment.", "format": "uuid", "nullable": true } } } } }, "examples": { "TEST event envelope": { "summary": "TEST event envelope", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "type": "payment.updated", "schemaVersion": 1, "createdAt": "2026-10-22T12:00:00Z", "environment": "test", "organizationId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "projectId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "resourceId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "data": { "paymentId": "8b0b3211-701a-4f36-88be-d522f61e7e45" } } }, "Live envelope (requires live signing setup)": { "summary": "Live envelope (requires live signing setup)", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "type": "payment.updated", "schemaVersion": 1, "createdAt": "2026-10-22T12:00:00Z", "environment": "live", "organizationId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "projectId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "resourceId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "data": { "paymentId": "8b0b3211-701a-4f36-88be-d522f61e7e45" } } } } } }, "required": true }, "responses": { "200": { "description": "Event recorded and reconciled. Empty body." }, "400": { "description": "validationError: Please check the information you entered.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/billing/webhook", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "id": [ "Supply a non-empty UUID." ] } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/billing/webhook", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "409": { "description": "orderConflict: Order data conflicts with the saved order/event. Retry the original details.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "orderConflict": { "summary": "orderConflict", "description": "Order data conflicts with the saved order/event. Retry the original details.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request conflict", "status": 409, "detail": "Order data conflicts with the saved order/event. Retry the original details.", "instance": "/api/billing/webhook", "code": "orderConflict", "traceId": "00-example-trace-id", "message": "Order data conflicts with the saved order/event. Retry the original details." } } } } } }, "413": { "description": "payloadTooLarge: Request too large", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "payloadTooLarge": { "summary": "payloadTooLarge", "description": "Request too large", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request too large", "status": 413, "detail": "Request too large", "instance": "/api/billing/webhook", "code": "payloadTooLarge", "traceId": "00-example-trace-id", "message": "Request too large" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/billing/webhook", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/billing/webhook", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } }, "security": [ ] } }, "/api/billing/subscriptions/invoices": { "get": { "tags": [ "Billing" ], "summary": "List your sandbox invoice simulations", "description": "Return immutable JSON simulation snapshots for the authenticated account only. These TEST documents are not legal invoices or fiscal evidence; this endpoint does not generate PDFs.\n\n### Own TEST invoice simulations\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/billing/subscriptions/invoices' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/billing/subscriptions/invoices\", {method: \"GET\", credentials: \"same-origin\", headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}});\nconst data = await response.json();\nif (!response.ok) throw new Error(data.code);\n```\n\n**C#**\n\n```csharp\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/billing/subscriptions/invoices\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```", "operationId": "ListSandboxInvoices", "responses": { "200": { "description": "Account-owned immutable TEST JSON simulations; no PDF or legal/fiscal invoice.", "content": { "application/json": { "schema": { "type": "array", "items": { "required": [ "receiptId", "agreementId", "snapshot", "createdAt" ], "type": "object", "properties": { "receiptId": { "type": "string" }, "agreementId": { "type": "string" }, "snapshot": { "required": [ "environment", "documentType", "number", "legalInvoice", "fiscalized" ], "type": "object", "properties": { "environment": { "type": "string", "description": "TEST or PROD. TEST never grants a real subscription." }, "documentType": { "type": "string" }, "number": { "type": "string" }, "legalInvoice": { "type": "boolean" }, "fiscalized": { "type": "boolean" } } }, "createdAt": { "type": "string" } } } }, "example": [ { "receiptId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "agreementId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "snapshot": { "environment": "TEST", "documentType": "simulation", "number": "TEST-SUB-EXAMPLE", "legalInvoice": false, "fiscalized": false }, "createdAt": "2026-11-01T10:00:00Z" } ] } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/billing/subscriptions/invoices", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/billing/subscriptions/invoices", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } } } } }, "/api/billing/subscriptions": { "get": { "tags": [ "Billing" ], "summary": "List sandbox subscriptions", "description": "TEST only. Payments are processed by Kvadrati Pay. Test payments do not activate production access. Approval opens the payment page; return here and refresh the status. A subscription already exists or these details conflict. Reload the list; retry unchanged details after a timeout.\n\n### List sandbox subscriptions\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/billing/subscriptions' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/billing/subscriptions\", {method: \"GET\", credentials: \"same-origin\", headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}});\nconst data = await response.json();\nif (!response.ok) throw new Error(data.code);\n```\n\n**C#**\n\n```csharp\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/billing/subscriptions\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```", "operationId": "ListSubscriptions", "responses": { "200": { "description": "TEST only; no production entitlement or fiscal evidence is implied.", "content": { "application/json": { "schema": { "type": "array", "items": { "required": [ "id", "plan", "provider", "environment", "status", "paidThrough", "nextBilling", "approvalUrl" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "plan": { "type": "string", "description": "Effective account plan or purchased plan identifier." }, "provider": { "type": "string" }, "environment": { "type": "string", "description": "TEST or PROD. TEST never grants a real subscription." }, "status": { "type": "string", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "paidThrough": { "type": "string", "nullable": true }, "nextBilling": { "type": "string", "nullable": true }, "approvalUrl": { "type": "string", "nullable": true } } } }, "example": [ { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "provider": "stripe", "environment": "TEST", "status": "Pending", "paidThrough": null, "nextBilling": null, "approvalUrl": null } ] } } }, "400": { "description": "validation: validation", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validation": { "summary": "validation", "description": "validation", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "validation", "instance": "/api/billing/subscriptions", "code": "validation", "traceId": "00-example-trace-id", "message": "validation", "errors": { "request": [ "validation" ] } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/billing/subscriptions", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "404": { "description": "notFound: Resource not found", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "notFound": { "summary": "notFound", "description": "Resource not found", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Resource not found", "status": 404, "detail": "Resource not found", "instance": "/api/billing/subscriptions", "code": "notFound", "traceId": "00-example-trace-id", "message": "Resource not found" } } } } } }, "409": { "description": "orderConflict: Order data conflicts with the saved order/event. Retry the original details.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "orderConflict": { "summary": "orderConflict", "description": "Order data conflicts with the saved order/event. Retry the original details.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request conflict", "status": 409, "detail": "Order data conflicts with the saved order/event. Retry the original details.", "instance": "/api/billing/subscriptions", "code": "orderConflict", "traceId": "00-example-trace-id", "message": "Order data conflicts with the saved order/event. Retry the original details." } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/billing/subscriptions", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "paymentsUnavailable: Checkout is disabled or incompletely configured.; quoteRequired: No price is configured; request a quotation.; paymentPending: Status is uncertain. Retry the same order ID; do not create a replacement order.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "paymentsUnavailable": { "summary": "paymentsUnavailable", "description": "Checkout is disabled or incompletely configured.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Checkout is disabled or incompletely configured.", "instance": "/api/billing/subscriptions", "code": "paymentsUnavailable", "traceId": "00-example-trace-id", "message": "Checkout is disabled or incompletely configured." } }, "quoteRequired": { "summary": "quoteRequired", "description": "No price is configured; request a quotation.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "No price is configured; request a quotation.", "instance": "/api/billing/subscriptions", "code": "quoteRequired", "traceId": "00-example-trace-id", "message": "No price is configured; request a quotation." } }, "paymentPending": { "summary": "paymentPending", "description": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "instance": "/api/billing/subscriptions", "code": "paymentPending", "traceId": "00-example-trace-id", "message": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "orderId": "8b0b3211-701a-4f36-88be-d522f61e7e45" } } } } } } } }, "post": { "tags": [ "Billing" ], "summary": "Create or retry a sandbox subscription", "description": "TEST only. Payments are processed by Kvadrati Pay. Test payments do not activate production access. Approval opens the payment page; return here and refresh the status. A subscription already exists or these details conflict. Reload the list; retry unchanged details after a timeout. Sandbox checkout currently requires a Slovenian test billing profile. Stripe cancellation is at period end; PayPal cancellation stops further renewals immediately. Verified test paid-through status is retained.\n\n### Create or retry a sandbox subscription\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/billing/subscriptions' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"plan\": \"start\", \"provider\": \"stripe\"}'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/billing/subscriptions\", {method: \"POST\", credentials: \"same-origin\", headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\", \"Content-Type\": \"application/json\"}, body: JSON.stringify({\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"plan\": \"start\", \"provider\": \"stripe\"})});\nconst data = await response.json();\nif (!response.ok) throw new Error(data.code);\n```\n\n**C#**\n\n```csharp\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/billing/subscriptions\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nrequest.Content = new StringContent(\"{\\\"id\\\": \\\"8b0b3211-701a-4f36-88be-d522f61e7e45\\\", \\\"plan\\\": \\\"start\\\", \\\"provider\\\": \\\"stripe\\\"}\", System.Text.Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```", "operationId": "CreateSubscription", "requestBody": { "description": "{\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"plan\": \"start\", \"provider\": \"stripe\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionInput" }, "examples": { "Create or retry a sandbox subscription": { "summary": "Create or retry a sandbox subscription", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "provider": "stripe" } } } } }, "required": true }, "responses": { "202": { "description": "TEST only; no production entitlement or fiscal evidence is implied.", "content": { "application/json": { "schema": { "required": [ "id", "plan", "provider", "environment", "status", "paidThrough", "nextBilling", "approvalUrl" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "plan": { "type": "string", "description": "Effective account plan or purchased plan identifier." }, "provider": { "type": "string" }, "environment": { "type": "string", "description": "TEST or PROD. TEST never grants a real subscription." }, "status": { "type": "string", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "paidThrough": { "type": "string", "nullable": true }, "nextBilling": { "type": "string", "nullable": true }, "approvalUrl": { "type": "string", "nullable": true } } }, "example": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "provider": "stripe", "environment": "TEST", "status": "Pending", "paidThrough": null, "nextBilling": null, "approvalUrl": null } } } }, "400": { "description": "validation: validation", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validation": { "summary": "validation", "description": "validation", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "validation", "instance": "/api/billing/subscriptions", "code": "validation", "traceId": "00-example-trace-id", "message": "validation", "errors": { "request": [ "validation" ] } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/billing/subscriptions", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "404": { "description": "notFound: Resource not found", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "notFound": { "summary": "notFound", "description": "Resource not found", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Resource not found", "status": 404, "detail": "Resource not found", "instance": "/api/billing/subscriptions", "code": "notFound", "traceId": "00-example-trace-id", "message": "Resource not found" } } } } } }, "409": { "description": "orderConflict: Order data conflicts with the saved order/event. Retry the original details.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "orderConflict": { "summary": "orderConflict", "description": "Order data conflicts with the saved order/event. Retry the original details.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request conflict", "status": 409, "detail": "Order data conflicts with the saved order/event. Retry the original details.", "instance": "/api/billing/subscriptions", "code": "orderConflict", "traceId": "00-example-trace-id", "message": "Order data conflicts with the saved order/event. Retry the original details." } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/billing/subscriptions", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "paymentsUnavailable: Checkout is disabled or incompletely configured.; quoteRequired: No price is configured; request a quotation.; paymentPending: Status is uncertain. Retry the same order ID; do not create a replacement order.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "paymentsUnavailable": { "summary": "paymentsUnavailable", "description": "Checkout is disabled or incompletely configured.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Checkout is disabled or incompletely configured.", "instance": "/api/billing/subscriptions", "code": "paymentsUnavailable", "traceId": "00-example-trace-id", "message": "Checkout is disabled or incompletely configured." } }, "quoteRequired": { "summary": "quoteRequired", "description": "No price is configured; request a quotation.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "No price is configured; request a quotation.", "instance": "/api/billing/subscriptions", "code": "quoteRequired", "traceId": "00-example-trace-id", "message": "No price is configured; request a quotation." } }, "paymentPending": { "summary": "paymentPending", "description": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "instance": "/api/billing/subscriptions", "code": "paymentPending", "traceId": "00-example-trace-id", "message": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "orderId": "8b0b3211-701a-4f36-88be-d522f61e7e45" } } } } } } } } }, "/api/billing/subscriptions/{id}": { "get": { "tags": [ "Billing" ], "summary": "Read your sandbox subscription", "description": "TEST only. Payments are processed by Kvadrati Pay. Test payments do not activate production access. Approval opens the payment page; return here and refresh the status. A subscription already exists or these details conflict. Reload the list; retry unchanged details after a timeout.\n\n### Read your sandbox subscription\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/billing/subscriptions/8b0b3211-701a-4f36-88be-d522f61e7e45' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/billing/subscriptions/8b0b3211-701a-4f36-88be-d522f61e7e45\", {method: \"GET\", credentials: \"same-origin\", headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}});\nconst data = await response.json();\nif (!response.ok) throw new Error(data.code);\n```\n\n**C#**\n\n```csharp\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/billing/subscriptions/8b0b3211-701a-4f36-88be-d522f61e7e45\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```", "operationId": "GetSubscription", "parameters": [ { "name": "id", "in": "path", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "8b0b3211-701a-4f36-88be-d522f61e7e45" } ], "responses": { "200": { "description": "TEST only; no production entitlement or fiscal evidence is implied.", "content": { "application/json": { "schema": { "required": [ "id", "plan", "provider", "environment", "status", "paidThrough", "nextBilling", "approvalUrl" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "plan": { "type": "string", "description": "Effective account plan or purchased plan identifier." }, "provider": { "type": "string" }, "environment": { "type": "string", "description": "TEST or PROD. TEST never grants a real subscription." }, "status": { "type": "string", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "paidThrough": { "type": "string", "nullable": true }, "nextBilling": { "type": "string", "nullable": true }, "approvalUrl": { "type": "string", "nullable": true } } }, "example": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "provider": "stripe", "environment": "TEST", "status": "Pending", "paidThrough": null, "nextBilling": null, "approvalUrl": null } } } }, "400": { "description": "validation: validation", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validation": { "summary": "validation", "description": "validation", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "validation", "instance": "/api/billing/subscriptions/{id:guid}", "code": "validation", "traceId": "00-example-trace-id", "message": "validation", "errors": { "request": [ "validation" ] } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/billing/subscriptions/{id:guid}", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "404": { "description": "notFound: Resource not found", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "notFound": { "summary": "notFound", "description": "Resource not found", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Resource not found", "status": 404, "detail": "Resource not found", "instance": "/api/billing/subscriptions/{id:guid}", "code": "notFound", "traceId": "00-example-trace-id", "message": "Resource not found" } } } } } }, "409": { "description": "orderConflict: Order data conflicts with the saved order/event. Retry the original details.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "orderConflict": { "summary": "orderConflict", "description": "Order data conflicts with the saved order/event. Retry the original details.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request conflict", "status": 409, "detail": "Order data conflicts with the saved order/event. Retry the original details.", "instance": "/api/billing/subscriptions/{id:guid}", "code": "orderConflict", "traceId": "00-example-trace-id", "message": "Order data conflicts with the saved order/event. Retry the original details." } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/billing/subscriptions/{id:guid}", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "paymentsUnavailable: Checkout is disabled or incompletely configured.; quoteRequired: No price is configured; request a quotation.; paymentPending: Status is uncertain. Retry the same order ID; do not create a replacement order.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "paymentsUnavailable": { "summary": "paymentsUnavailable", "description": "Checkout is disabled or incompletely configured.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Checkout is disabled or incompletely configured.", "instance": "/api/billing/subscriptions/{id:guid}", "code": "paymentsUnavailable", "traceId": "00-example-trace-id", "message": "Checkout is disabled or incompletely configured." } }, "quoteRequired": { "summary": "quoteRequired", "description": "No price is configured; request a quotation.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "No price is configured; request a quotation.", "instance": "/api/billing/subscriptions/{id:guid}", "code": "quoteRequired", "traceId": "00-example-trace-id", "message": "No price is configured; request a quotation." } }, "paymentPending": { "summary": "paymentPending", "description": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "instance": "/api/billing/subscriptions/{id:guid}", "code": "paymentPending", "traceId": "00-example-trace-id", "message": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "orderId": "8b0b3211-701a-4f36-88be-d522f61e7e45" } } } } } } } } }, "/api/billing/subscriptions/{id}/cancel": { "post": { "tags": [ "Billing" ], "summary": "Cancel your sandbox subscription", "description": "TEST only. Payments are processed by Kvadrati Pay. Test payments do not activate production access. Approval opens the payment page; return here and refresh the status. A subscription already exists or these details conflict. Reload the list; retry unchanged details after a timeout. Sandbox checkout currently requires a Slovenian test billing profile. Stripe cancellation is at period end; PayPal cancellation stops further renewals immediately. Verified test paid-through status is retained.\n\n### Cancel sandbox renewals\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/billing/subscriptions/8b0b3211-701a-4f36-88be-d522f61e7e45/cancel' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"actionId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\"}'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/billing/subscriptions/8b0b3211-701a-4f36-88be-d522f61e7e45/cancel\", {method: \"POST\", credentials: \"same-origin\", headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\", \"Content-Type\": \"application/json\"}, body: JSON.stringify({\"actionId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\"})});\nconst data = await response.json();\nif (!response.ok) throw new Error(data.code);\n```\n\n**C#**\n\n```csharp\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/billing/subscriptions/8b0b3211-701a-4f36-88be-d522f61e7e45/cancel\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nrequest.Content = new StringContent(\"{\\\"actionId\\\": \\\"8b0b3211-701a-4f36-88be-d522f61e7e45\\\"}\", System.Text.Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```", "operationId": "CancelSubscription", "parameters": [ { "name": "id", "in": "path", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "8b0b3211-701a-4f36-88be-d522f61e7e45" } ], "requestBody": { "description": "{\"actionId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionAction" }, "examples": { "Cancel sandbox renewals": { "summary": "Cancel sandbox renewals", "value": { "actionId": "8b0b3211-701a-4f36-88be-d522f61e7e45" } } } } }, "required": true }, "responses": { "202": { "description": "TEST only; no production entitlement or fiscal evidence is implied.", "content": { "application/json": { "schema": { "required": [ "id", "plan", "provider", "environment", "status", "paidThrough", "nextBilling", "approvalUrl" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "plan": { "type": "string", "description": "Effective account plan or purchased plan identifier." }, "provider": { "type": "string" }, "environment": { "type": "string", "description": "TEST or PROD. TEST never grants a real subscription." }, "status": { "type": "string", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "paidThrough": { "type": "string", "nullable": true }, "nextBilling": { "type": "string", "nullable": true }, "approvalUrl": { "type": "string", "nullable": true } } }, "example": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "provider": "stripe", "environment": "TEST", "status": "Pending", "paidThrough": null, "nextBilling": null, "approvalUrl": null } } } }, "400": { "description": "validation: validation", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validation": { "summary": "validation", "description": "validation", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "validation", "instance": "/api/billing/subscriptions/{id:guid}/cancel", "code": "validation", "traceId": "00-example-trace-id", "message": "validation", "errors": { "request": [ "validation" ] } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/billing/subscriptions/{id:guid}/cancel", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "404": { "description": "notFound: Resource not found", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "notFound": { "summary": "notFound", "description": "Resource not found", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Resource not found", "status": 404, "detail": "Resource not found", "instance": "/api/billing/subscriptions/{id:guid}/cancel", "code": "notFound", "traceId": "00-example-trace-id", "message": "Resource not found" } } } } } }, "409": { "description": "orderConflict: Order data conflicts with the saved order/event. Retry the original details.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "orderConflict": { "summary": "orderConflict", "description": "Order data conflicts with the saved order/event. Retry the original details.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request conflict", "status": 409, "detail": "Order data conflicts with the saved order/event. Retry the original details.", "instance": "/api/billing/subscriptions/{id:guid}/cancel", "code": "orderConflict", "traceId": "00-example-trace-id", "message": "Order data conflicts with the saved order/event. Retry the original details." } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/billing/subscriptions/{id:guid}/cancel", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "paymentsUnavailable: Checkout is disabled or incompletely configured.; quoteRequired: No price is configured; request a quotation.; paymentPending: Status is uncertain. Retry the same order ID; do not create a replacement order.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "paymentsUnavailable": { "summary": "paymentsUnavailable", "description": "Checkout is disabled or incompletely configured.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Checkout is disabled or incompletely configured.", "instance": "/api/billing/subscriptions/{id:guid}/cancel", "code": "paymentsUnavailable", "traceId": "00-example-trace-id", "message": "Checkout is disabled or incompletely configured." } }, "quoteRequired": { "summary": "quoteRequired", "description": "No price is configured; request a quotation.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "No price is configured; request a quotation.", "instance": "/api/billing/subscriptions/{id:guid}/cancel", "code": "quoteRequired", "traceId": "00-example-trace-id", "message": "No price is configured; request a quotation." } }, "paymentPending": { "summary": "paymentPending", "description": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "instance": "/api/billing/subscriptions/{id:guid}/cancel", "code": "paymentPending", "traceId": "00-example-trace-id", "message": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "orderId": "8b0b3211-701a-4f36-88be-d522f61e7e45" } } } } } } } } }, "/api/billing/subscriptions/{id}/refresh": { "post": { "tags": [ "Billing" ], "summary": "Refresh your sandbox subscription", "description": "TEST only. Payments are processed by Kvadrati Pay. Test payments do not activate production access. Approval opens the payment page; return here and refresh the status. A subscription already exists or these details conflict. Reload the list; retry unchanged details after a timeout.\n\n### Refresh your sandbox subscription\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/billing/subscriptions/8b0b3211-701a-4f36-88be-d522f61e7e45/refresh' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"actionId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\"}'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/billing/subscriptions/8b0b3211-701a-4f36-88be-d522f61e7e45/refresh\", {method: \"POST\", credentials: \"same-origin\", headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\", \"Content-Type\": \"application/json\"}, body: JSON.stringify({\"actionId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\"})});\nconst data = await response.json();\nif (!response.ok) throw new Error(data.code);\n```\n\n**C#**\n\n```csharp\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/billing/subscriptions/8b0b3211-701a-4f36-88be-d522f61e7e45/refresh\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nrequest.Content = new StringContent(\"{\\\"actionId\\\": \\\"8b0b3211-701a-4f36-88be-d522f61e7e45\\\"}\", System.Text.Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```", "operationId": "RefreshSubscription", "parameters": [ { "name": "id", "in": "path", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "required": true, "schema": { "type": "string", "format": "uuid" }, "example": "8b0b3211-701a-4f36-88be-d522f61e7e45" } ], "requestBody": { "description": "{\"actionId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\"}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionAction" }, "examples": { "Refresh your sandbox subscription": { "summary": "Refresh your sandbox subscription", "value": { "actionId": "8b0b3211-701a-4f36-88be-d522f61e7e45" } } } } }, "required": true }, "responses": { "202": { "description": "TEST only; no production entitlement or fiscal evidence is implied.", "content": { "application/json": { "schema": { "required": [ "id", "plan", "provider", "environment", "status", "paidThrough", "nextBilling", "approvalUrl" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "plan": { "type": "string", "description": "Effective account plan or purchased plan identifier." }, "provider": { "type": "string" }, "environment": { "type": "string", "description": "TEST or PROD. TEST never grants a real subscription." }, "status": { "type": "string", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "paidThrough": { "type": "string", "nullable": true }, "nextBilling": { "type": "string", "nullable": true }, "approvalUrl": { "type": "string", "nullable": true } } }, "example": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "plan": "start", "provider": "stripe", "environment": "TEST", "status": "Pending", "paidThrough": null, "nextBilling": null, "approvalUrl": null } } } }, "400": { "description": "validation: validation", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validation": { "summary": "validation", "description": "validation", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "validation", "instance": "/api/billing/subscriptions/{id:guid}/refresh", "code": "validation", "traceId": "00-example-trace-id", "message": "validation", "errors": { "request": [ "validation" ] } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/billing/subscriptions/{id:guid}/refresh", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "404": { "description": "notFound: Resource not found", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "notFound": { "summary": "notFound", "description": "Resource not found", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Resource not found", "status": 404, "detail": "Resource not found", "instance": "/api/billing/subscriptions/{id:guid}/refresh", "code": "notFound", "traceId": "00-example-trace-id", "message": "Resource not found" } } } } } }, "409": { "description": "orderConflict: Order data conflicts with the saved order/event. Retry the original details.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "orderConflict": { "summary": "orderConflict", "description": "Order data conflicts with the saved order/event. Retry the original details.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request conflict", "status": 409, "detail": "Order data conflicts with the saved order/event. Retry the original details.", "instance": "/api/billing/subscriptions/{id:guid}/refresh", "code": "orderConflict", "traceId": "00-example-trace-id", "message": "Order data conflicts with the saved order/event. Retry the original details." } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/billing/subscriptions/{id:guid}/refresh", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "paymentsUnavailable: Checkout is disabled or incompletely configured.; quoteRequired: No price is configured; request a quotation.; paymentPending: Status is uncertain. Retry the same order ID; do not create a replacement order.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "paymentsUnavailable": { "summary": "paymentsUnavailable", "description": "Checkout is disabled or incompletely configured.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Checkout is disabled or incompletely configured.", "instance": "/api/billing/subscriptions/{id:guid}/refresh", "code": "paymentsUnavailable", "traceId": "00-example-trace-id", "message": "Checkout is disabled or incompletely configured." } }, "quoteRequired": { "summary": "quoteRequired", "description": "No price is configured; request a quotation.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "No price is configured; request a quotation.", "instance": "/api/billing/subscriptions/{id:guid}/refresh", "code": "quoteRequired", "traceId": "00-example-trace-id", "message": "No price is configured; request a quotation." } }, "paymentPending": { "summary": "paymentPending", "description": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "instance": "/api/billing/subscriptions/{id:guid}/refresh", "code": "paymentPending", "traceId": "00-example-trace-id", "message": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "orderId": "8b0b3211-701a-4f36-88be-d522f61e7e45" } } } } } } } } }, "/api/billing/subscriptions/webhook": { "post": { "tags": [ "Billing" ], "summary": "Receive a signed Pay subscription event", "description": "Verify the Pay signature and reconcile via authenticated Pay status. No direct provider or FURS request. Duplicate delivery must not extend access twice; renewal-upcoming events send no reminder.\n\n### Receive a signed Pay subscription event\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/billing/subscriptions/webhook' \\\n --header 'Accept: application/json' \\\n --header 'Kvadrati-Signature: REPLACE_WITH_PAY_SIGNATURE' \\\n --header 'Kvadrati-Event-Id: 8b0b3211-701a-4f36-88be-d522f61e7e45' \\\n --header 'Kvadrati-Endpoint-Id: REPLACE_WITH_ENDPOINT_UUID' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"type\": \"subscription.payment_succeeded\", \"createdAtUtc\": \"2026-11-01T10:00:00Z\", \"data\": {\"subscriptionId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"reference\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"environment\": \"Test\"}}'\n```\n\n**JavaScript**\n\n```javascript\nconst response = await fetch(\"/api/billing/subscriptions/webhook\", {method: \"POST\", credentials: \"same-origin\", headers: {\"Accept\": \"application/json\", \"Kvadrati-Signature\": \"REPLACE_WITH_PAY_SIGNATURE\", \"Kvadrati-Event-Id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"Kvadrati-Endpoint-Id\": \"REPLACE_WITH_ENDPOINT_UUID\", \"Content-Type\": \"application/json\"}, body: JSON.stringify({\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"type\": \"subscription.payment_succeeded\", \"createdAtUtc\": \"2026-11-01T10:00:00Z\", \"data\": {\"subscriptionId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"reference\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"environment\": \"Test\"}})});\nconst data = await response.json();\nif (!response.ok) throw new Error(data.code);\n```\n\n**C#**\n\n```csharp\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/billing/subscriptions/webhook\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Kvadrati-Signature\", \"REPLACE_WITH_PAY_SIGNATURE\");\nrequest.Headers.TryAddWithoutValidation(\"Kvadrati-Event-Id\", \"8b0b3211-701a-4f36-88be-d522f61e7e45\");\nrequest.Headers.TryAddWithoutValidation(\"Kvadrati-Endpoint-Id\", \"REPLACE_WITH_ENDPOINT_UUID\");\nrequest.Content = new StringContent(\"{\\\"id\\\": \\\"8b0b3211-701a-4f36-88be-d522f61e7e45\\\", \\\"type\\\": \\\"subscription.payment_succeeded\\\", \\\"createdAtUtc\\\": \\\"2026-11-01T10:00:00Z\\\", \\\"data\\\": {\\\"subscriptionId\\\": \\\"8b0b3211-701a-4f36-88be-d522f61e7e45\\\", \\\"reference\\\": \\\"8b0b3211-701a-4f36-88be-d522f61e7e45\\\", \\\"environment\\\": \\\"Test\\\"}}\", System.Text.Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nConsole.WriteLine(await response.Content.ReadAsStringAsync());\n```", "operationId": "SubscriptionWebhook", "parameters": [ { "name": "Kvadrati-Signature", "in": "header", "description": "Gateway HMAC: v=1;kid=;t=;h=. Sign exact raw UTF-8 bytes with the configured gateway protocol.", "required": true, "schema": { "type": "string" } }, { "name": "Kvadrati-Event-Id", "in": "header", "description": "Event UUID matching the signed envelope. Identical retries reuse the same ID.", "required": true, "schema": { "type": "string" } }, { "name": "Kvadrati-Endpoint-Id", "in": "header", "description": "Configured webhook endpoint UUID; included in the signature scope.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "{\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"type\": \"subscription.payment_succeeded\", \"createdAtUtc\": \"2026-11-01T10:00:00Z\", \"data\": {\"subscriptionId\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"reference\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"environment\": \"Test\"}}", "content": { "application/json": { "schema": { "required": [ "id", "type", "createdAtUtc", "data" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "type": { "type": "string" }, "createdAtUtc": { "type": "string" }, "data": { "required": [ "subscriptionId", "reference", "environment" ], "type": "object", "properties": { "subscriptionId": { "type": "string" }, "reference": { "type": "string" }, "environment": { "type": "string", "description": "TEST or PROD. TEST never grants a real subscription." } } } } }, "examples": { "Receive a signed Pay subscription event": { "summary": "Receive a signed Pay subscription event", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "type": "subscription.payment_succeeded", "createdAtUtc": "2026-11-01T10:00:00Z", "data": { "subscriptionId": "8b0b3211-701a-4f36-88be-d522f61e7e45", "reference": "8b0b3211-701a-4f36-88be-d522f61e7e45", "environment": "Test" } } } } } }, "required": true }, "responses": { "200": { "description": "TEST only; no production entitlement or fiscal evidence is implied.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "validation: validation", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validation": { "summary": "validation", "description": "validation", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "validation", "instance": "/api/billing/subscriptions/webhook", "code": "validation", "traceId": "00-example-trace-id", "message": "validation", "errors": { "request": [ "validation" ] } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/billing/subscriptions/webhook", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "404": { "description": "notFound: Resource not found", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "notFound": { "summary": "notFound", "description": "Resource not found", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Resource not found", "status": 404, "detail": "Resource not found", "instance": "/api/billing/subscriptions/webhook", "code": "notFound", "traceId": "00-example-trace-id", "message": "Resource not found" } } } } } }, "409": { "description": "orderConflict: Order data conflicts with the saved order/event. Retry the original details.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "orderConflict": { "summary": "orderConflict", "description": "Order data conflicts with the saved order/event. Retry the original details.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request conflict", "status": 409, "detail": "Order data conflicts with the saved order/event. Retry the original details.", "instance": "/api/billing/subscriptions/webhook", "code": "orderConflict", "traceId": "00-example-trace-id", "message": "Order data conflicts with the saved order/event. Retry the original details." } } } } } }, "413": { "description": "payloadTooLarge: Request too large", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "payloadTooLarge": { "summary": "payloadTooLarge", "description": "Request too large", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request too large", "status": 413, "detail": "Request too large", "instance": "/api/billing/subscriptions/webhook", "code": "payloadTooLarge", "traceId": "00-example-trace-id", "message": "Request too large" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/billing/subscriptions/webhook", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "paymentsUnavailable: Checkout is disabled or incompletely configured.; quoteRequired: No price is configured; request a quotation.; paymentPending: Status is uncertain. Retry the same order ID; do not create a replacement order.; serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "paymentsUnavailable": { "summary": "paymentsUnavailable", "description": "Checkout is disabled or incompletely configured.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Checkout is disabled or incompletely configured.", "instance": "/api/billing/subscriptions/webhook", "code": "paymentsUnavailable", "traceId": "00-example-trace-id", "message": "Checkout is disabled or incompletely configured." } }, "quoteRequired": { "summary": "quoteRequired", "description": "No price is configured; request a quotation.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "No price is configured; request a quotation.", "instance": "/api/billing/subscriptions/webhook", "code": "quoteRequired", "traceId": "00-example-trace-id", "message": "No price is configured; request a quotation." } }, "paymentPending": { "summary": "paymentPending", "description": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "instance": "/api/billing/subscriptions/webhook", "code": "paymentPending", "traceId": "00-example-trace-id", "message": "Status is uncertain. Retry the same order ID; do not create a replacement order.", "orderId": "8b0b3211-701a-4f36-88be-d522f61e7e45" } }, "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/billing/subscriptions/webhook", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } }, "security": [ ] } }, "/api/companies/suggestions": { "get": { "tags": [ "Companies" ], "summary": "Company name suggestions", "description": "Name and city suggestions do not consume the daily allowance. Selecting a company consumes one lookup.\n\n### Slovenian prefix\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/companies/suggestions?country=SI&q=Pr' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/companies/suggestions?country=SI&q=Pr\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/companies/suggestions?country=SI&q=Pr\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Croatian prefix\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/companies/suggestions?country=HR&q=Pr' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/companies/suggestions?country=HR&q=Pr\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/companies/suggestions?country=HR&q=Pr\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### No-match example\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/companies/suggestions?country=SI&q=NoMatchingCompany' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/companies/suggestions?country=SI&q=NoMatchingCompany\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/companies/suggestions?country=SI&q=NoMatchingCompany\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Serbian Cyrillic prefix\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/companies/suggestions?country=RS&q=%D0%9F%D1%80' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/companies/suggestions?country=RS&q=%D0%9F%D1%80\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/companies/suggestions?country=RS&q=%D0%9F%D1%80\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Bosnian prefix\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/companies/suggestions?country=BA&q=Pr' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/companies/suggestions?country=BA&q=Pr\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/companies/suggestions?country=BA&q=Pr\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Montenegrin prefix\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/companies/suggestions?country=ME&q=Pr' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/companies/suggestions?country=ME&q=Pr\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/companies/suggestions?country=ME&q=Pr\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "CompanySuggestions", "parameters": [ { "name": "country", "in": "query", "description": "Required: SI, HR, RS, BA or ME. Live data depends on completed imports; inspect /api/config sources. Anonymous demo is fictional.", "required": true, "schema": { "enum": [ "SI", "HR", "RS", "BA", "ME" ], "type": "string" }, "example": "SI" }, { "name": "q", "in": "query", "description": "Required company-name prefix, 2–120 normalized Unicode characters; at most 12 results. Cyrillic remains Cyrillic.", "required": true, "schema": { "maxLength": 120, "minLength": 2, "type": "string" }, "example": "Pr" } ], "responses": { "200": { "description": "Up to 12 name/city suggestions. Does not consume daily or per-account minute lookup allowance; general request throttling still applies.", "content": { "application/json": { "schema": { "type": "array", "items": { "required": [ "country", "source", "sourceId", "name", "city" ], "type": "object", "properties": { "country": { "type": "string", "description": "Country code for this source record." }, "source": { "type": "string", "description": "Source provenance. DEMO means fictional records, not official data." }, "sourceId": { "type": "string", "description": "Stable identifier within country/source; use with country, not company name, as identity." }, "name": { "type": "string", "description": "Company legal name or account display name, depending on response." }, "city": { "type": "string", "description": "Separately supplied locality; empty if unavailable." } } } }, "examples": { "success": { "summary": "success", "value": [ { "country": "SI", "source": "DEMO", "sourceId": "demo-si", "name": "Primer podjetja d.o.o.", "city": "Ljubljana" } ] }, "noMatches": { "summary": "noMatches", "value": [ ] } } } } }, "400": { "description": "validationError: Please check the information you entered.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/companies/suggestions", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "country": [ "Choose SI, HR, RS or BA." ], "q": [ "Enter 2–120 normalized Unicode characters. Whitespace alone is invalid." ] } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/companies/suggestions", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/companies/suggestions", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/companies/suggestions", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } } } }, "/api/companies": { "get": { "tags": [ "Companies" ], "summary": "Autocomplete companies", "description": "Fill a form from locally prepared registry data. Requires confirmed account and Bearer access token. In DemoMode this route also returns fictional records; inspect source. Every admitted valid lookup counts, including empty results. Quotas are shared across tokens and instances; reset at Europe/Ljubljana midnight, including DST. Choose country and enter at least two normalized Unicode characters. Returns up to 12 objects; [] is a successful no-match result. No remote registry call is made during search. Check /api/config for imported source availability and revision. Source removal is not proof of legal dissolution.\n\nIP protection: 300 requests/minute globally, plus a shared 120/minute route policy. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### Slovenian prefix\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/companies?country=SI&q=Pr' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/companies?country=SI&q=Pr\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/companies?country=SI&q=Pr\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Croatian prefix\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/companies?country=HR&q=Pr' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/companies?country=HR&q=Pr\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/companies?country=HR&q=Pr\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### No-match example\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/companies?country=SI&q=NoMatchingCompany' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/companies?country=SI&q=NoMatchingCompany\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/companies?country=SI&q=NoMatchingCompany\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Serbian Cyrillic prefix\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/companies?country=RS&q=%D0%9F%D1%80' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/companies?country=RS&q=%D0%9F%D1%80\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/companies?country=RS&q=%D0%9F%D1%80\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Bosnian prefix\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/companies?country=BA&q=Pr' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/companies?country=BA&q=Pr\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/companies?country=BA&q=Pr\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Montenegrin prefix\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/companies?country=ME&q=Pr' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer REPLACE_WITH_ACCESS_TOKEN'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/companies?country=ME&q=Pr\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Authorization\": \"Bearer REPLACE_WITH_ACCESS_TOKEN\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/companies?country=ME&q=Pr\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Authorization\", \"Bearer REPLACE_WITH_ACCESS_TOKEN\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "SearchCompanies", "parameters": [ { "name": "country", "in": "query", "description": "Required: SI, HR, RS, BA or ME. Live data depends on completed imports; inspect /api/config sources. Anonymous demo is fictional.", "required": true, "schema": { "enum": [ "SI", "HR", "RS", "BA", "ME" ], "type": "string" }, "example": "SI" }, { "name": "q", "in": "query", "description": "Required company-name prefix, 2–120 normalized Unicode characters; at most 12 results. Cyrillic remains Cyrillic.", "required": true, "schema": { "maxLength": 120, "minLength": 2, "type": "string" }, "example": "Pr" }, { "name": "source", "in": "query", "description": "Source name for exact selection. Supply together with sourceId.", "schema": { "type": "string" } }, { "name": "sourceId", "in": "query", "description": "Source identifier for exact selection. Supply together with source.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full company details. Each accepted request consumes one lookup. Optional source and sourceId together select an exact identity; q=selection can be used for that request.", "headers": { "X-RateLimit-Limit": { "description": "Account daily allowance; present after account quota evaluation. IP-limit rejection happens earlier and omits these headers.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Account daily allowance; present after account quota evaluation. IP-limit rejection happens earlier and omits these headers.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Reset instant as Unix seconds; present after account quota evaluation.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "required": [ "country", "sourceId", "name", "taxNumber", "registrationNumber", "address", "postalCode", "city", "activity", "source", "updatedAt", "originalAddress", "companyType", "legalForm", "typeEvidence", "registryStatus" ], "type": "object", "properties": { "country": { "type": "string", "description": "Country code for this source record." }, "sourceId": { "type": "string", "description": "Stable identifier within country/source; use with country, not company name, as identity." }, "name": { "type": "string", "description": "Company legal name or account display name, depending on response." }, "taxNumber": { "type": "string", "description": "Tax/VAT identifier when supplied by the registry; empty if unavailable." }, "registrationNumber": { "type": "string", "description": "Company registration identifier; empty if unavailable." }, "address": { "type": "string", "description": "Normalized street address. SI removes only matching duplicate postal/city suffixes." }, "postalCode": { "type": "string", "description": "Separately supplied postal code; empty if unavailable." }, "city": { "type": "string", "description": "Separately supplied locality; empty if unavailable." }, "activity": { "type": "string", "description": "Source activity code/description when available." }, "source": { "type": "string", "description": "Source provenance. DEMO means fictional records, not official data." }, "updatedAt": { "type": "string", "description": "Stored record update timestamp; not a guarantee that the upstream registry is current.", "format": "date-time" }, "originalAddress": { "type": "string", "description": "Preserved unnormalized source address." }, "companyType": { "type": "string", "description": "Company type" }, "legalForm": { "type": "string", "description": "Official legal form" }, "typeEvidence": { "type": "string", "description": "Classification basis" }, "registryStatus": { "type": "string", "description": "Source status" } } } }, "examples": { "success": { "summary": "success", "value": [ { "country": "SI", "sourceId": "demo-si", "name": "Primer podjetja d.o.o.", "taxNumber": "", "registrationNumber": "", "address": "Vzorčna ulica 1", "postalCode": "1000", "city": "Ljubljana", "activity": "", "source": "DEMO", "updatedAt": "1970-01-01T01:00:00+01:00", "originalAddress": "", "companyType": "limitedLiability", "legalForm": "", "typeEvidence": "name_inference", "registryStatus": "" } ] }, "noMatches": { "summary": "noMatches", "value": [ ] } } } } }, "400": { "description": "validationError: Please check the information you entered.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/companies", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "country": [ "Choose SI, HR, RS or BA." ], "q": [ "Enter 2–120 normalized Unicode characters. Whitespace alone is invalid." ] } } } } } } }, "401": { "description": "unauthorized: Authentication required", "headers": { "WWW-Authenticate": { "description": "Bearer challenge for protected endpoints; explicit login and webhook failures omit it.", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unauthorized": { "summary": "unauthorized", "description": "Authentication required", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Authentication required", "status": 401, "detail": "Authentication required", "instance": "/api/companies", "code": "unauthorized", "traceId": "00-example-trace-id", "message": "Authentication required" } } } } } }, "403": { "description": "accountInactive: The account is inactive or unconfirmed.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "accountInactive": { "summary": "accountInactive", "description": "The account is inactive or unconfirmed.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Access denied", "status": 403, "detail": "The account is inactive or unconfirmed.", "instance": "/api/companies", "code": "accountInactive", "traceId": "00-example-trace-id", "message": "The account is inactive or unconfirmed." } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded; dailyLimit: Daily limit; minuteLimit: Too many requests in one minute. Please try again shortly.; concurrencyLimit: You have reached the concurrent request limit.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Account daily allowance; present after account quota evaluation. IP-limit rejection happens earlier and omits these headers.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Account daily allowance; present after account quota evaluation. IP-limit rejection happens earlier and omits these headers.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Reset instant as Unix seconds; present after account quota evaluation.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/companies", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } }, "dailyLimit": { "summary": "dailyLimit", "description": "Daily limit", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Daily limit", "instance": "/api/companies", "code": "dailyLimit", "traceId": "00-example-trace-id", "message": "Daily limit", "limit": 5, "remaining": 0, "resetAt": "2026-10-23T00:00:00+02:00" } }, "minuteLimit": { "summary": "minuteLimit", "description": "Too many requests in one minute. Please try again shortly.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Too many requests in one minute. Please try again shortly.", "instance": "/api/companies", "code": "minuteLimit", "traceId": "00-example-trace-id", "message": "Too many requests in one minute. Please try again shortly.", "limit": 5, "remaining": 0, "resetAt": "2026-10-23T00:00:00+02:00" } }, "concurrencyLimit": { "summary": "concurrencyLimit", "description": "You have reached the concurrent request limit.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "You have reached the concurrent request limit.", "instance": "/api/companies", "code": "concurrencyLimit", "traceId": "00-example-trace-id", "message": "You have reached the concurrent request limit.", "limit": 5, "remaining": 0, "resetAt": "2026-10-23T00:00:00+02:00" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/companies", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } } } }, "/api/demo/companies": { "get": { "tags": [ "Demo" ], "summary": "Search fictional demo companies", "description": "Fictional records for testing autocomplete without an account. No live-registry freshness or national coverage is implied. Choose country and enter at least two normalized Unicode characters. Returns up to 12 objects; [] is a successful no-match result. No remote registry call is made during search. Check /api/config for imported source availability and revision. Source removal is not proof of legal dissolution.\n\nIP protection: 300 requests/minute globally, plus a shared 120/minute route policy. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### Slovenian prefix\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/demo/companies?country=SI&q=Pr' \\\n --header 'Accept: application/json'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/demo/companies?country=SI&q=Pr\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/demo/companies?country=SI&q=Pr\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Croatian prefix\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/demo/companies?country=HR&q=Pr' \\\n --header 'Accept: application/json'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/demo/companies?country=HR&q=Pr\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/demo/companies?country=HR&q=Pr\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Cyrillic demo\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/demo/companies?country=RS&q=%D0%9F%D1%80' \\\n --header 'Accept: application/json'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/demo/companies?country=RS&q=%D0%9F%D1%80\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/demo/companies?country=RS&q=%D0%9F%D1%80\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Bosnian prefix\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/demo/companies?country=BA&q=Pr' \\\n --header 'Accept: application/json'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/demo/companies?country=BA&q=Pr\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/demo/companies?country=BA&q=Pr\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Montenegrin prefix\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/demo/companies?country=ME&q=Pr' \\\n --header 'Accept: application/json'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/demo/companies?country=ME&q=Pr\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/demo/companies?country=ME&q=Pr\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "SearchDemo", "parameters": [ { "name": "country", "in": "query", "description": "Required: SI, HR, RS, BA or ME. Live data depends on completed imports; inspect /api/config sources. Anonymous demo is fictional.", "required": true, "schema": { "enum": [ "SI", "HR", "RS", "BA", "ME" ], "type": "string" }, "example": "SI" }, { "name": "q", "in": "query", "description": "Required company-name prefix, 2–120 normalized Unicode characters; at most 12 results. Cyrillic remains Cyrillic.", "required": true, "schema": { "maxLength": 120, "minLength": 2, "type": "string" }, "example": "Pr" } ], "responses": { "200": { "description": "Up to 12 objects; [] means no match. DEMO identifies fictional records.", "content": { "application/json": { "schema": { "type": "array", "items": { "required": [ "country", "sourceId", "name", "taxNumber", "registrationNumber", "address", "postalCode", "city", "activity", "source", "updatedAt", "originalAddress", "companyType", "legalForm", "typeEvidence", "registryStatus" ], "type": "object", "properties": { "country": { "type": "string", "description": "Country code for this source record." }, "sourceId": { "type": "string", "description": "Stable identifier within country/source; use with country, not company name, as identity." }, "name": { "type": "string", "description": "Company legal name or account display name, depending on response." }, "taxNumber": { "type": "string", "description": "Tax/VAT identifier when supplied by the registry; empty if unavailable." }, "registrationNumber": { "type": "string", "description": "Company registration identifier; empty if unavailable." }, "address": { "type": "string", "description": "Normalized street address. SI removes only matching duplicate postal/city suffixes." }, "postalCode": { "type": "string", "description": "Separately supplied postal code; empty if unavailable." }, "city": { "type": "string", "description": "Separately supplied locality; empty if unavailable." }, "activity": { "type": "string", "description": "Source activity code/description when available." }, "source": { "type": "string", "description": "Source provenance. DEMO means fictional records, not official data." }, "updatedAt": { "type": "string", "description": "Stored record update timestamp; not a guarantee that the upstream registry is current.", "format": "date-time" }, "originalAddress": { "type": "string", "description": "Preserved unnormalized source address." }, "companyType": { "type": "string", "description": "Company type" }, "legalForm": { "type": "string", "description": "Official legal form" }, "typeEvidence": { "type": "string", "description": "Classification basis" }, "registryStatus": { "type": "string", "description": "Source status" } } } }, "examples": { "success": { "summary": "success", "value": [ { "country": "SI", "sourceId": "demo-si", "name": "Primer podjetja d.o.o.", "taxNumber": "", "registrationNumber": "", "address": "Vzorčna ulica 1", "postalCode": "1000", "city": "Ljubljana", "activity": "", "source": "DEMO", "updatedAt": "1970-01-01T01:00:00+01:00", "originalAddress": "", "companyType": "limitedLiability", "legalForm": "", "typeEvidence": "name_inference", "registryStatus": "" } ] }, "noMatches": { "summary": "noMatches", "value": [ ] } } } } }, "400": { "description": "validationError: Please check the information you entered.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/demo/companies", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "country": [ "Choose SI, HR, RS or BA." ], "q": [ "Enter 2–120 normalized Unicode characters. Whitespace alone is invalid." ] } } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/demo/companies", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/demo/companies", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } }, "security": [ ] } }, "/api/submissions": { "post": { "tags": [ "Forms" ], "summary": "Send a contact or quotation enquiry", "description": "Queue operator notification and customer acknowledgement. Requires same-origin Origin and Turnstile action matching kind. Reuse the UUID for deduplication on retry. 202 is acceptance, not mail delivery, payment or subscription activation. Use /api/auth/register for accounts. DemoMode returns 503.\n\nIP protection: 300 requests/minute globally, plus a shared 5/minute route policy. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### Contact message\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/submissions' \\\n --header 'Accept: application/json' \\\n --header 'Origin: http://localhost:5278' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"kind\": \"contact\", \"email\": \"developer@example.com\", \"locale\": \"en\", \"name\": \"Example User\", \"message\": \"Please explain integration options.\", \"country\": \"SI\", \"turnstileToken\": \"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\"}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/submissions\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({\"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\", \"kind\": \"contact\", \"email\": \"developer@example.com\", \"locale\": \"en\", \"name\": \"Example User\", \"message\": \"Please explain integration options.\", \"country\": \"SI\", \"turnstileToken\": \"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\"})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/submissions\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Origin\", \"http://localhost:5278\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"id\": \"8b0b3211-701a-4f36-88be-d522f61e7e45\",\n \"kind\": \"contact\",\n \"email\": \"developer@example.com\",\n \"locale\": \"en\",\n \"name\": \"Example User\",\n \"message\": \"Please explain integration options.\",\n \"country\": \"SI\",\n \"turnstileToken\": \"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\"\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Pro quotation enquiry\n\n**cURL**\n\n```bash\ncurl --request POST 'http://localhost:5278/api/submissions' \\\n --header 'Accept: application/json' \\\n --header 'Origin: http://localhost:5278' \\\n --header 'Content-Type: application/json' \\\n --data-raw '{\"id\": \"6d4f7638-8db2-42b7-8b9b-08a1c019ed50\", \"kind\": \"order\", \"email\": \"developer@example.com\", \"locale\": \"en\", \"name\": \"Example User\", \"message\": \"Please quote the Pro plan.\", \"country\": \"SI\", \"turnstileToken\": \"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\"}'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/submissions\", {\n method: \"POST\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\", \"Content-Type\": \"application/json\"},\n body: JSON.stringify({\"id\": \"6d4f7638-8db2-42b7-8b9b-08a1c019ed50\", \"kind\": \"order\", \"email\": \"developer@example.com\", \"locale\": \"en\", \"name\": \"Example User\", \"message\": \"Please quote the Pro plan.\", \"country\": \"SI\", \"turnstileToken\": \"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\"})\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Post, \"http://localhost:5278/api/submissions\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nrequest.Headers.TryAddWithoutValidation(\"Origin\", \"http://localhost:5278\");\nrequest.Content = new StringContent(\"\"\"\n{\n \"id\": \"6d4f7638-8db2-42b7-8b9b-08a1c019ed50\",\n \"kind\": \"order\",\n \"email\": \"developer@example.com\",\n \"locale\": \"en\",\n \"name\": \"Example User\",\n \"message\": \"Please quote the Pro plan.\",\n \"country\": \"SI\",\n \"turnstileToken\": \"REPLACE_WITH_FRESH_TURNSTILE_TOKEN\"\n}\n\"\"\", Encoding.UTF8, \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "SubmitEnquiry", "parameters": [ { "name": "Origin", "in": "header", "description": "Exact service scheme and host, including local port. Required for CAPTCHA submissions and cookie-based refresh. Browser supplies it automatically.", "required": true, "schema": { "type": "string" }, "example": "http://localhost:5278" } ], "requestBody": { "description": "Required id, kind, email, locale, name, message, country and turnstileToken. No password field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitRequest" }, "examples": { "Contact message": { "summary": "Contact message", "value": { "id": "8b0b3211-701a-4f36-88be-d522f61e7e45", "kind": "contact", "email": "developer@example.com", "locale": "en", "name": "Example User", "message": "Please explain integration options.", "country": "SI", "turnstileToken": "REPLACE_WITH_FRESH_TURNSTILE_TOKEN" } }, "Pro quotation enquiry": { "summary": "Pro quotation enquiry", "value": { "id": "6d4f7638-8db2-42b7-8b9b-08a1c019ed50", "kind": "order", "email": "developer@example.com", "locale": "en", "name": "Example User", "message": "Please quote the Pro plan.", "country": "SI", "turnstileToken": "REPLACE_WITH_FRESH_TURNSTILE_TOKEN" } } } } }, "required": true }, "responses": { "202": { "description": "Successful response.", "content": { "application/json": { "schema": { "required": [ "message" ], "type": "object", "properties": { "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." } } }, "examples": { "success": { "summary": "success", "value": { "message": "Your enquiry has been accepted." } } } } } }, "400": { "description": "validationError: Please check the information you entered.; captchaError: Complete verification and try again.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message", "errors" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." } } }, "examples": { "validationError": { "summary": "validationError", "description": "Please check the information you entered.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Please check the information you entered.", "instance": "/api/submissions", "code": "validationError", "traceId": "00-example-trace-id", "message": "Please check the information you entered.", "errors": { "id": [ "Supply a non-empty UUID." ], "kind": [ "Choose contact or order." ], "email": [ "Enter a valid email, at most 254 characters." ], "locale": [ "Choose sl, hr, en, sr-Cyrl or bs." ], "name": [ "Enter a name of 1–200 characters." ], "message": [ "Supply a string of at most 5,000 characters." ], "country": [ "Choose SI, HR, RS or BA." ] } } }, "captchaError": { "summary": "captchaError", "description": "Complete verification and try again.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Invalid request", "status": 400, "detail": "Complete verification and try again.", "instance": "/api/submissions", "code": "captchaError", "traceId": "00-example-trace-id", "message": "Complete verification and try again.", "errors": { "turnstileToken": [ "Complete verification and try again." ] } } } } } } }, "413": { "description": "payloadTooLarge: Request too large", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "payloadTooLarge": { "summary": "payloadTooLarge", "description": "Request too large", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Request too large", "status": 413, "detail": "Request too large", "instance": "/api/submissions", "code": "payloadTooLarge", "traceId": "00-example-trace-id", "message": "Request too large" } } } } } }, "415": { "description": "unsupportedMediaType: Unsupported content type", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "unsupportedMediaType": { "summary": "unsupportedMediaType", "description": "Unsupported content type", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Unsupported content type", "status": 415, "detail": "Unsupported content type", "instance": "/api/submissions", "code": "unsupportedMediaType", "traceId": "00-example-trace-id", "message": "Unsupported content type" } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/submissions", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable; demoFormsDisabled: Forms are disabled in demo mode.", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/submissions", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } }, "demoFormsDisabled": { "summary": "demoFormsDisabled", "description": "Forms are disabled in demo mode.", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Forms are disabled in demo mode.", "instance": "/api/submissions", "code": "demoFormsDisabled", "traceId": "00-example-trace-id", "message": "Forms are disabled in demo mode." } } } } } } }, "security": [ ] } }, "/health": { "get": { "tags": [ "Service" ], "summary": "Check process liveness", "description": "Use a lightweight liveness probe. Returns plain text Healthy. Does not check database, imports, email or payment readiness. No authentication or body.\n\nIP protection: 300 requests/minute globally. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### Liveness probe\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/health' \\\n --header 'Accept: application/json'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/health\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconsole.log(text);\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/health\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Monitoring probe\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/health' \\\n --header 'Accept: application/json'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/health\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconsole.log(text);\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/health\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "GetHealth", "responses": { "200": { "description": "Process running. UTF-8 text, not JSON.", "content": { "text/plain": { "schema": { "type": "string" }, "examples": { "success": { "summary": "success", "value": "Healthy" } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/health", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/health", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } }, "security": [ ] } }, "/api/config": { "get": { "tags": [ "Service" ], "summary": "Read public website capabilities", "description": "Initialize public feature flags and CAPTCHA/analytics identifiers. No secret keys are returned. authAvailable means the endpoints exist; it does not establish database readiness. authTurnstileAvailable checks configuration presence only.\n\nIP protection: 300 requests/minute globally. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### Initialize website\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/config' \\\n --header 'Accept: application/json'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/config\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/config\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Refresh capabilities\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/config' \\\n --header 'Accept: application/json'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/config\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/config\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "GetConfig", "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "required": [ "demo", "turnstileSiteKey", "analyticsId", "serbiaAvailable", "authAvailable", "authTurnstileAvailable", "contactAvailable", "sources", "pricing" ], "type": "object", "properties": { "demo": { "type": "boolean", "description": "Whether the application is in fictional demo mode." }, "turnstileSiteKey": { "type": "string", "description": "Public CAPTCHA widget identifier; never the secret." }, "analyticsId": { "type": "string", "description": "Public measurement identifier; browser loads analytics only after consent." }, "serbiaAvailable": { "type": "boolean", "description": "Whether a Serbian snapshot has been successfully imported in this live instance." }, "authAvailable": { "type": "boolean", "description": "Authentication endpoints exist; this does not check database readiness." }, "authTurnstileAvailable": { "type": "boolean", "description": "Authentication CAPTCHA keys are configured; this does not test Cloudflare." }, "contactAvailable": { "type": "boolean", "description": "Contact enabled outside DemoMode with CAPTCHA configuration." }, "sources": { "type": "array", "items": { "type": "object" }, "description": "Latest successful imports: country, source, revision, count and checkedAt. removalsAllowed=false means observation-only imports without deletions; quarantinedRows counts rejected rows. count is the accepted row count for this import, not all retained records. Empty in demo mode." }, "pricing": { "required": [ "currency", "interval", "taxIncluded", "startNetAmountMinor", "proNetAmountMinor" ], "type": "object", "properties": { "currency": { "type": "string", "description": "EUR." }, "interval": { "type": "string" }, "taxIncluded": { "type": "boolean" }, "startNetAmountMinor": { "type": "integer" }, "proNetAmountMinor": { "type": "integer" } } } } }, "examples": { "success": { "summary": "success", "value": { "demo": true, "turnstileSiteKey": "", "analyticsId": "", "serbiaAvailable": false, "authAvailable": true, "authTurnstileAvailable": false, "contactAvailable": false, "sources": [ ], "pricing": { "currency": "EUR", "interval": "month", "taxIncluded": false, "startNetAmountMinor": 999, "proNetAmountMinor": 2999 } } }, "observation_import_illustrative": { "summary": "observation_import_illustrative", "value": { "demo": false, "turnstileSiteKey": "", "analyticsId": "", "serbiaAvailable": false, "authAvailable": true, "authTurnstileAvailable": false, "contactAvailable": false, "sources": [ { "country": "BA", "source": "BA-Brcko", "revision": "example-revision", "count": 1000, "checkedAt": "2026-10-22T12:00:00Z", "removalsAllowed": false, "quarantinedRows": 3 } ], "pricing": { "currency": "EUR", "interval": "month", "taxIncluded": false, "startNetAmountMinor": 999, "proNetAmountMinor": 2999 } } }, "historical_import_illustrative": { "summary": "historical_import_illustrative", "value": { "demo": false, "turnstileSiteKey": "", "analyticsId": "", "serbiaAvailable": false, "authAvailable": true, "authTurnstileAvailable": false, "contactAvailable": false, "sources": [ { "country": "ME", "source": "ME-Poreska-2020", "revision": "2020-09-22;example", "count": 51007, "checkedAt": "2026-10-22T12:00:00Z", "sourceDate": "2020-09-22", "historical": true, "removalsAllowed": false, "quarantinedRows": 0 } ], "pricing": { "currency": "EUR", "interval": "month", "taxIncluded": false, "startNetAmountMinor": 999, "proNetAmountMinor": 2999 } } } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/config", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/config", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } }, "security": [ ] } }, "/api/plans": { "get": { "tags": [ "Service" ], "summary": "Compare package allowances", "description": "Display Free, Start and Pro limits. No prices are returned. Free: 5/day; Start: 1000/day; Pro: 10000/day. Minute and concurrency limits also apply. Paid periods are 30 days; pricing requires a quotation.\n\nIP protection: 300 requests/minute globally. HTTP 429 includes Retry-After. Unsupported HTTP verbs return 405; send JSON for body-based methods.\n\n### Pricing comparison\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/plans' \\\n --header 'Accept: application/json'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/plans\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/plans\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```\n\n### Check current limits\n\n**cURL**\n\n```bash\ncurl --request GET 'http://localhost:5278/api/plans' \\\n --header 'Accept: application/json'\n```\n\n**JavaScript**\n\n```javascript\n// Run from this site. Browser supplies Origin; cross-origin calls are not enabled.\nconst response = await fetch(\"/api/plans\", {\n method: \"GET\",\n credentials: \"same-origin\",\n headers: {\"Accept\": \"application/json\"}\n});\nif (!response.ok) {\n const problem = await response.json();\n console.error(problem.code, problem.errors, problem.traceId);\n throw new Error(problem.detail);\n}\nconst text = await response.text();\nconst data = text ? JSON.parse(text) : null;\n```\n\n**C#**\n\n```csharp\nusing System.Net.Http;\nusing System.Text;\n\nusing var client = new HttpClient();\nusing var request = new HttpRequestMessage(HttpMethod.Get, \"http://localhost:5278/api/plans\");\nrequest.Headers.TryAddWithoutValidation(\"Accept\", \"application/json\");\nusing var response = await client.SendAsync(request);\nvar body = await response.Content.ReadAsStringAsync();\n// Failure body: application/problem+json; inspect code, errors and traceId.\nConsole.WriteLine($\"{(int)response.StatusCode}: {body}\");\n```", "operationId": "GetPlans", "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "array", "items": { "required": [ "id", "daily", "perMinute", "concurrent" ], "type": "object", "properties": { "id": { "type": "string", "description": "Account UUID, order UUID or plan identifier as defined by the containing object.", "format": "uuid" }, "daily": { "type": "integer", "description": "Maximum accepted lookups per Ljubljana calendar day." }, "perMinute": { "type": "integer", "description": "Per-account minute cap." }, "concurrent": { "type": "integer", "description": "Maximum simultaneous account lookups." } } } }, "examples": { "success": { "summary": "success", "value": [ { "id": "free", "daily": 5, "perMinute": 5, "concurrent": 1 }, { "id": "start", "daily": 1000, "perMinute": 20, "concurrent": 2 }, { "id": "pro", "daily": 10000, "perMinute": 60, "concurrent": 4 } ] } } } } }, "429": { "description": "rateLimited: Rate limit exceeded", "headers": { "Retry-After": { "description": "Seconds to wait before retrying. Account concurrency/minute reset is reflected by the response.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "rateLimited": { "summary": "rateLimited", "description": "Rate limit exceeded", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5", "title": "Rate limit exceeded", "status": 429, "detail": "Rate limit exceeded", "instance": "/api/plans", "code": "rateLimited", "traceId": "00-example-trace-id", "message": "Rate limit exceeded" } } } } } }, "503": { "description": "serviceUnavailable: Service temporarily unavailable", "content": { "application/problem+json": { "schema": { "required": [ "type", "title", "status", "detail", "instance", "code", "traceId", "message" ], "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "description": "Persisted order lifecycle state. Accepted/Created is not proof of payment. NeedsAttention requires operator review." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable outcome or error code." }, "traceId": { "type": "string" }, "message": { "type": "string", "description": "Localized human-readable outcome; do not branch on translated wording." }, "limit": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "remaining": { "type": "integer", "description": "Optional context for quota or pending-payment errors." }, "resetAt": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "orderId": { "type": "string", "description": "Optional context for quota or pending-payment errors." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Field names mapped to arrays of validation messages; present on HTTP 400." } } }, "examples": { "serviceUnavailable": { "summary": "serviceUnavailable", "description": "Service temporarily unavailable", "value": { "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.6", "title": "Service temporarily unavailable", "status": 503, "detail": "Service temporarily unavailable", "instance": "/api/plans", "code": "serviceUnavailable", "traceId": "00-example-trace-id", "message": "Service temporarily unavailable" } } } } } } }, "security": [ ] } } }, "components": { "schemas": { "AdminPlanInput": { "required": [ "actionId", "plan", "expiresAt", "reason" ], "type": "object", "properties": { "actionId": { "type": "string", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "format": "uuid" }, "plan": { "enum": [ "start", "pro" ], "type": "string", "description": "start or pro. Server determines the price and 30-day duration. Active cross-plan switching is unavailable.", "nullable": true }, "expiresAt": { "type": "string", "description": "Valid through (UTC)", "format": "date-time", "nullable": true }, "reason": { "type": "string", "description": "Reason for change", "nullable": true } }, "additionalProperties": false }, "BankConfirmationInput": { "required": [ "actionId", "amountMinor", "reference" ], "type": "object", "properties": { "actionId": { "type": "string", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "format": "uuid" }, "amountMinor": { "type": "integer", "description": "Amount received (EUR)", "format": "int64" }, "reference": { "type": "string", "description": "Unique transaction identifier from bank statement", "nullable": true } }, "additionalProperties": false }, "BillingOrderInput": { "required": [ "id", "plan", "method", "billingName", "billingAddress" ], "type": "object", "properties": { "id": { "type": "string", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "format": "uuid" }, "plan": { "enum": [ "start", "pro" ], "type": "string", "description": "start or pro. Server determines the price and 30-day duration. Active cross-plan switching is unavailable.", "nullable": true }, "method": { "enum": [ "stripe", "paypal", "bank" ], "type": "string", "description": "stripe, paypal or bank. Bank returns instructions, not proof of receipt.", "nullable": true }, "billingName": { "maxLength": 200, "minLength": 1, "type": "string", "description": "Company name", "nullable": true }, "billingAddress": { "maxLength": 1000, "minLength": 1, "type": "string", "description": "Required billing address, 1–1,000 characters.", "nullable": true }, "billingVatId": { "maxLength": 100, "type": "string", "description": "Optional VAT ID, at most 100 characters; null is allowed.", "nullable": true } }, "additionalProperties": false }, "CompanyDto": { "type": "object", "properties": { "country": { "enum": [ "SI", "HR", "RS", "BA", "ME" ], "type": "string", "description": "Required: SI, HR, RS, BA or ME. Live data depends on completed imports; inspect /api/config sources. Anonymous demo is fictional.", "nullable": true }, "sourceId": { "type": "string", "description": "Source identifier for exact selection. Supply together with source.", "nullable": true }, "name": { "maxLength": 200, "minLength": 1, "type": "string", "description": "Display name; required, 1–200 characters.", "nullable": true }, "taxNumber": { "type": "string", "description": "Tax number / VAT ID", "nullable": true }, "registrationNumber": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code", "nullable": true }, "city": { "type": "string", "description": "City", "nullable": true }, "activity": { "type": "string", "nullable": true }, "source": { "type": "string", "description": "Source name for exact selection. Supply together with sourceId.", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time" }, "originalAddress": { "type": "string", "nullable": true }, "companyType": { "type": "string", "nullable": true }, "legalForm": { "type": "string", "nullable": true }, "typeEvidence": { "type": "string", "nullable": true }, "registryStatus": { "type": "string", "nullable": true } }, "additionalProperties": false }, "Confirmation": { "required": [ "token" ], "type": "object", "properties": { "token": { "type": "string", "description": "Single-use email link token. Confirmation: 24 hours; password reset: one hour.", "nullable": true } }, "additionalProperties": false }, "CustomerProfile": { "type": "object", "properties": { "customerType": { "type": "string", "description": "Customer type", "nullable": true }, "billingName": { "maxLength": 200, "minLength": 1, "type": "string", "description": "Company name", "nullable": true }, "street": { "type": "string", "description": "Street and building number", "nullable": true }, "postalCode": { "type": "string", "description": "Postal code", "nullable": true }, "city": { "type": "string", "description": "City", "nullable": true }, "countryCode": { "type": "string", "description": "Country", "nullable": true }, "taxNumber": { "type": "string", "description": "Tax number / VAT ID", "nullable": true }, "vatStatus": { "type": "string", "description": "VAT status", "nullable": true } }, "additionalProperties": false }, "ForgotInput": { "required": [ "email", "locale", "turnstileToken" ], "type": "object", "properties": { "email": { "maxLength": 254, "type": "string", "description": "Valid email address, at most 254 characters. Authentication normalizes case.", "format": "email", "nullable": true }, "locale": { "enum": [ "sl", "hr", "en", "sr-Cyrl", "bs", "cnr" ], "type": "string", "description": "sl, hr, en, sr-Cyrl, bs or cnr. Login and reset default to en.", "nullable": true }, "turnstileToken": { "type": "string", "description": "Fresh Cloudflare widget token. Expected action: register, forgot, contact or order. Server verifies action and hostname.", "nullable": true } }, "additionalProperties": false }, "LoginInput": { "required": [ "email", "password" ], "type": "object", "properties": { "email": { "maxLength": 254, "type": "string", "description": "Valid email address, at most 254 characters. Authentication normalizes case.", "format": "email", "nullable": true }, "password": { "maxLength": 128, "type": "string", "description": "12–128 characters for registration/reset. Login accepts the existing password up to 128 characters. Never log this field.", "format": "password", "nullable": true, "writeOnly": true }, "locale": { "enum": [ "sl", "hr", "en", "sr-Cyrl", "bs", "cnr" ], "type": "string", "description": "sl, hr, en, sr-Cyrl, bs or cnr. Login and reset default to en.", "nullable": true } }, "additionalProperties": false }, "PlanLimits": { "type": "object", "properties": { "id": { "type": "string", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "nullable": true }, "daily": { "type": "integer", "format": "int32" }, "perMinute": { "type": "integer", "format": "int32" }, "concurrent": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "PublicPricing": { "type": "object", "properties": { "currency": { "type": "string", "nullable": true }, "interval": { "type": "string", "nullable": true }, "taxIncluded": { "type": "boolean" }, "startNetAmountMinor": { "type": "integer", "format": "int32" }, "proNetAmountMinor": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "PublicPricingBooleanStringStringBooleanRegistrySourceStatusIReadOnlyListBooleanBooleanBoolean<>f__AnonymousType7": { "type": "object", "properties": { "pricing": { "$ref": "#/components/schemas/PublicPricing" }, "demo": { "type": "boolean" }, "turnstileSiteKey": { "type": "string", "nullable": true }, "analyticsId": { "type": "string", "nullable": true }, "serbiaAvailable": { "type": "boolean" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/RegistrySourceStatus" }, "nullable": true }, "authAvailable": { "type": "boolean" }, "authTurnstileAvailable": { "type": "boolean" }, "contactAvailable": { "type": "boolean" } }, "additionalProperties": false }, "RefreshInput": { "type": "object", "properties": { "refreshToken": { "type": "string", "description": "Optional rotating refresh token. Cookie mode requires JSON {} and the same-origin browser cookie. Never reuse a consumed token.", "nullable": true } }, "additionalProperties": false }, "RegisterInput": { "required": [ "name", "email", "password", "locale", "turnstileToken", "billing" ], "type": "object", "properties": { "name": { "maxLength": 200, "minLength": 1, "type": "string", "description": "Display name; required, 1–200 characters.", "nullable": true }, "email": { "maxLength": 254, "type": "string", "description": "Valid email address, at most 254 characters. Authentication normalizes case.", "format": "email", "nullable": true }, "password": { "maxLength": 128, "minLength": 12, "type": "string", "description": "12–128 characters for registration/reset. Login accepts the existing password up to 128 characters. Never log this field.", "format": "password", "nullable": true, "writeOnly": true }, "locale": { "enum": [ "sl", "hr", "en", "sr-Cyrl", "bs", "cnr" ], "type": "string", "description": "sl, hr, en, sr-Cyrl, bs or cnr. Login and reset default to en.", "nullable": true }, "turnstileToken": { "type": "string", "description": "Fresh Cloudflare widget token. Expected action: register, forgot, contact or order. Server verifies action and hostname.", "nullable": true }, "billing": { "$ref": "#/components/schemas/CustomerProfile" } }, "additionalProperties": false }, "RegistrySourceStatus": { "type": "object", "properties": { "country": { "enum": [ "SI", "HR", "RS", "BA", "ME" ], "type": "string", "description": "Required: SI, HR, RS, BA or ME. Live data depends on completed imports; inspect /api/config sources. Anonymous demo is fictional.", "nullable": true }, "source": { "type": "string", "description": "Source name for exact selection. Supply together with sourceId.", "nullable": true }, "revision": { "type": "string", "nullable": true }, "count": { "type": "integer", "format": "int64" }, "checkedAt": { "type": "string", "format": "date-time" }, "removalsAllowed": { "type": "boolean" }, "quarantinedRows": { "type": "integer", "format": "int32" }, "sourceDate": { "type": "string", "format": "date", "nullable": true }, "historical": { "type": "boolean" } }, "additionalProperties": false }, "ResetInput": { "required": [ "token", "password" ], "type": "object", "properties": { "token": { "type": "string", "description": "Single-use email link token. Confirmation: 24 hours; password reset: one hour.", "nullable": true }, "password": { "maxLength": 128, "minLength": 12, "type": "string", "description": "12–128 characters for registration/reset. Login accepts the existing password up to 128 characters. Never log this field.", "format": "password", "nullable": true, "writeOnly": true }, "locale": { "enum": [ "sl", "hr", "en", "sr-Cyrl", "bs", "cnr" ], "type": "string", "description": "sl, hr, en, sr-Cyrl, bs or cnr. Login and reset default to en.", "nullable": true } }, "additionalProperties": false }, "SubmitRequest": { "required": [ "id", "kind", "email", "locale", "name", "message", "country", "turnstileToken" ], "type": "object", "properties": { "id": { "type": "string", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "format": "uuid" }, "kind": { "enum": [ "contact", "order" ], "type": "string", "description": "contact or order (quotation enquiry). Neither creates a subscription.", "nullable": true }, "email": { "maxLength": 254, "type": "string", "description": "Valid email address, at most 254 characters. Authentication normalizes case.", "format": "email", "nullable": true }, "locale": { "enum": [ "sl", "hr", "en", "sr-Cyrl", "bs", "cnr" ], "type": "string", "description": "sl, hr, en, sr-Cyrl, bs or cnr. Login and reset default to en.", "nullable": true }, "name": { "maxLength": 200, "minLength": 1, "type": "string", "description": "Display name; required, 1–200 characters.", "nullable": true }, "message": { "maxLength": 5000, "type": "string", "description": "Required string, at most 5,000 characters. An empty string is accepted.", "nullable": true }, "country": { "enum": [ "SI", "HR", "RS", "BA", "ME" ], "type": "string", "description": "Required: SI, HR, RS, BA or ME. Live data depends on completed imports; inspect /api/config sources. Anonymous demo is fictional.", "nullable": true }, "turnstileToken": { "type": "string", "description": "Fresh Cloudflare widget token. Expected action: register, forgot, contact or order. Server verifies action and hostname.", "nullable": true } }, "additionalProperties": false }, "SubscriptionAction": { "type": "object", "properties": { "actionId": { "type": "string", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "format": "uuid" } }, "additionalProperties": false }, "SubscriptionInput": { "required": [ "id", "plan", "provider" ], "type": "object", "properties": { "id": { "type": "string", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "format": "uuid" }, "plan": { "enum": [ "start", "pro" ], "type": "string", "description": "start or pro. Server determines the price and 30-day duration. Active cross-plan switching is unavailable.", "nullable": true }, "provider": { "type": "string", "nullable": true } }, "additionalProperties": false }, "SupportInput": { "required": [ "accountId", "reason", "actionId" ], "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "description": "Reason for change", "nullable": true }, "actionId": { "type": "string", "description": "Non-empty UUID. For retries, reuse the same identifier and original data. On GET orders, identifies an order owned by the caller.", "format": "uuid" } }, "additionalProperties": false } }, "securitySchemes": { "Bearer": { "type": "http", "description": "Access token from POST /api/auth/login; expires after 15 minutes.", "scheme": "bearer", "bearerFormat": "opaque access token" } } }, "security": [ { "Bearer": [ ] } ], "tags": [ { "name": "Account" }, { "name": "Administration" }, { "name": "Billing" }, { "name": "Companies" }, { "name": "Demo" }, { "name": "Forms" }, { "name": "Service" } ] }