{ "openapi": "3.1.0", "info": { "title": "Invoice Navigator API", "description": "EU e-invoicing compliance API. Validate, auto-fix, and certify invoices against EN 16931, Peppol BIS 3.0, XRechnung, ZUGFeRD, and country-specific CIUS rules.\n\n## Authentication\n\nAll authenticated endpoints require a Bearer token:\n\n```\nAuthorization: Bearer sk_live_...\n```\n\nAPI keys are available at [invoicenavigator.eu/developers](https://www.invoicenavigator.eu/developers) (keys are created at signup and shown once on /welcome). Use `sk_test_` keys for development — same engine, same rules, no quota consumed.\n\n## Rate Limits\n\n| Tier | Requests/hour |\n|------|---------------|\n| Free (100 invoices/mo) | 60 |\n| Team / Pro (5,000 invoices/mo) | 100 |\n| Test mode (sk_test_) | 100 (fixed) |\n| Enterprise | Custom |\n\n## Errors\n\n| Status | Code | Meaning |\n|--------|------|---------|\n| 401 | `UNAUTHORIZED` / `KEY_EXPIRED` | Missing, invalid or expired key |\n| 402 | `QUOTA_EXCEEDED` | Metered allowance used up — `error.details.upgradeUrl` points at checkout |\n| 429 | `RATE_LIMITED` | Too many requests — honour `Retry-After` |\n\n## Try it without an account\n\n```\ncurl -X POST https://www.invoicenavigator.eu/api/developers/instant-key\n```\n\nreturns a 1-hour, 10-request `sk_test_` key plus a ready-made curl for `/v2/validate-and-fix`.\n\nRate limit headers are included in every response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.\n\n## Supported Formats\n\n- UBL 2.1 (Universal Business Language)\n- CII (Cross-Industry Invoice)\n- XRechnung 3.0 (Germany)\n- Peppol BIS Billing 3.0\n- Factur-X / ZUGFeRD 2.3 (Germany/France)", "version": "2.0.0", "contact": { "name": "Invoice Navigator", "url": "https://www.invoicenavigator.eu/developers", "email": "support@invoicenavigator.eu" }, "license": { "name": "Proprietary", "url": "https://www.invoicenavigator.eu/terms" } }, "servers": [ { "url": "https://www.invoicenavigator.eu/api", "description": "Production" }, { "url": "https://api.invoicenavigator.eu/api", "description": "Production (API host alias)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Validation", "description": "Validate invoices against EN 16931 and country-specific rules" }, { "name": "Fixer", "description": "Auto-remediate validation errors in invoices" }, { "name": "Evidence Packs", "description": "Generate and verify signed compliance evidence" }, { "name": "Conversion", "description": "Convert between UBL and CII invoice formats" }, { "name": "Countries", "description": "Country e-invoicing status and requirements" }, { "name": "Regulatory Intelligence", "description": "Deadlines, requirements, changes, and compliance scoring" }, { "name": "Reference Data", "description": "Validation error codes and compliance facts" }, { "name": "Health", "description": "API health and status" } ], "paths": { "/v1/validate": { "post": { "tags": [ "Validation" ], "summary": "Validate an e-invoice", "description": "Validate a single e-invoice against EN 16931 and country-specific rules. Returns validation result with errors, warnings, and extracted metadata.", "operationId": "validateInvoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "xml" ], "properties": { "xml": { "type": "string", "description": "Invoice XML content" }, "fileName": { "type": "string", "description": "Original filename for logging", "example": "invoice-2026-001.xml" }, "webhookUrl": { "type": "string", "format": "uri", "description": "URL to receive async webhook notification" }, "options": { "type": "object", "properties": { "ruleset_versions": { "type": "object", "description": "Pin specific ruleset versions" } } } } } } } }, "responses": { "200": { "description": "Validation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "402": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/v1/validate/batch": { "post": { "tags": [ "Validation" ], "summary": "Validate multiple invoices", "description": "Validate multiple invoices in a single request (up to 100).", "operationId": "validateBatch", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "invoices" ], "properties": { "invoices": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "xml" ], "properties": { "xml": { "type": "string" }, "fileName": { "type": "string" }, "id": { "type": "string", "description": "Your reference ID for this invoice" } } } } } } } } }, "responses": { "200": { "description": "Batch validation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchValidationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Batch validation requires an active plan" }, "429": { "$ref": "#/components/responses/RateLimited" }, "402": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/v1/fixer/categorize": { "post": { "tags": [ "Fixer" ], "summary": "Categorize validation errors", "description": "Categorize validation errors into auto-fixable, input-required, and blocked categories using the rule engine.", "operationId": "categorizeErrors", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "error_codes" ], "properties": { "error_codes": { "type": "array", "items": { "type": "string" }, "description": "Array of validation error codes to categorize" } } } } } }, "responses": { "200": { "description": "Errors categorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "categorized": { "type": "object", "properties": { "auto": { "type": "array", "items": { "type": "object" } }, "input": { "type": "array", "items": { "type": "object" } }, "blocked": { "type": "array", "items": { "type": "object" } } } }, "stats": { "type": "object", "properties": { "auto": { "type": "integer" }, "input": { "type": "integer" }, "blocked": { "type": "integer" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/fixer/fix": { "post": { "tags": [ "Fixer" ], "summary": "Auto-fix invoice errors", "description": "Apply automatic fixes to an invoice. Structural issues are remediated; financial fields are never modified. Consumes quota on success.", "operationId": "fixInvoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "xml", "error_codes" ], "properties": { "xml": { "type": "string", "description": "Invoice XML content" }, "error_codes": { "type": "array", "items": { "type": "string" }, "description": "Error codes to fix" }, "flow_id": { "type": "string", "description": "Existing flow ID for retries" } } } } } }, "responses": { "200": { "description": "Fixes applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Monthly quota exceeded" }, "402": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/v1/fixer/fix-with-input": { "post": { "tags": [ "Fixer" ], "summary": "Apply user-provided input fixes", "description": "Apply user-provided values to fix input-required errors. Must be called after `/fixer/fix` with an existing flow_id.", "operationId": "fixWithInput", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "xml", "values", "flow_id" ], "properties": { "xml": { "type": "string", "description": "Invoice XML content" }, "values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Field ID to value mappings" }, "skipped": { "type": "array", "items": { "type": "string" }, "description": "Error codes to skip" }, "error_codes": { "type": "array", "items": { "type": "string" } }, "flow_id": { "type": "string", "description": "Flow ID from /fixer/fix" } } } } } }, "responses": { "200": { "description": "Input fixes applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixWithInputResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "402": { "$ref": "#/components/responses/QuotaExceeded" } } } }, "/v1/fixer/usage": { "get": { "tags": [ "Fixer" ], "summary": "Get fix quota usage", "description": "Get current quota usage, subscription tier, and fix history.", "operationId": "getFixerUsage", "parameters": [], "responses": { "200": { "description": "Usage data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/fixer/download": { "get": { "tags": [ "Fixer" ], "summary": "Download fixed or original invoice XML", "description": "Download the fixed or original invoice XML for a completed fix flow.", "operationId": "downloadInvoice", "parameters": [ { "name": "flow_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Fix flow ID" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "fixed", "original" ], "default": "fixed" }, "description": "Which version to download" } ], "responses": { "200": { "description": "Invoice XML file", "content": { "application/xml": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Flow not found or XML not available" } } } }, "/v1/evidence-pack": { "post": { "tags": [ "Evidence Packs" ], "summary": "Generate Evidence Pack", "description": "Generate a cryptographically signed Evidence Pack for a validation result. Supports PDF or JSON output.", "operationId": "generateEvidencePack", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "validationRef" ], "properties": { "validationRef": { "type": "string", "description": "Validation reference ID from /validate" }, "invoiceXml": { "type": "string", "description": "Original XML for document hash computation" }, "invoiceMetadata": { "type": "object", "properties": { "invoiceNumber": { "type": "string" }, "issueDate": { "type": "string", "format": "date" }, "sellerName": { "type": "string" }, "buyerName": { "type": "string" }, "totalAmount": { "type": "number" }, "currency": { "type": "string" } } }, "format": { "type": "string", "enum": [ "pdf", "json" ], "default": "pdf" }, "companyName": { "type": "string", "description": "Company name on PDF" } } } } } }, "responses": { "200": { "description": "Evidence Pack generated", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "$ref": "#/components/schemas/SignedEvidencePack" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Validation not found" } } } }, "/v1/evidence-packs": { "get": { "tags": [ "Evidence Packs" ], "summary": "List Evidence Packs", "description": "List all evidence packs for your account with pagination and filtering.", "operationId": "listEvidencePacks", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Filter by created_at >= from" }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Filter by created_at <= to" }, { "name": "result", "in": "query", "schema": { "type": "string", "enum": [ "passed", "failed" ] } } ], "responses": { "200": { "description": "Evidence Packs list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidencePackListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/verify/{id}": { "get": { "tags": [ "Evidence Packs" ], "summary": "Verify an Evidence Pack", "description": "Verify that an Evidence Pack is authentic and was issued by Invoice Navigator. This is a public endpoint — no authentication required.", "operationId": "verifyEvidencePack", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Evidence Pack ID or verification code" }, { "name": "documentHash", "in": "query", "schema": { "type": "string" }, "description": "Optional document hash to verify" } ], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResponse" } } } }, "404": { "description": "Evidence Pack not found" } } } }, "/v1/convert": { "post": { "tags": [ "Conversion" ], "summary": "Convert invoice format", "description": "Convert an invoice between UBL and CII formats. Supports XRechnung, Peppol BIS, and Factur-X profiles. 10MB size limit.", "operationId": "convertInvoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source", "targetFormat" ], "properties": { "source": { "type": "string", "description": "Base64-encoded invoice XML" }, "sourceFormat": { "type": "string", "enum": [ "auto", "ubl-2.1", "xrechnung-ubl", "xrechnung-cii", "peppol-bis", "factur-x", "zugferd", "cii" ], "default": "auto", "description": "Source format (auto-detected if omitted)" }, "targetFormat": { "type": "string", "enum": [ "ubl-2.1", "xrechnung-ubl", "xrechnung-cii", "peppol-bis", "factur-x-minimum", "factur-x-basic", "factur-x-extended", "cii" ], "description": "Target format" }, "options": { "type": "object", "description": "Conversion options" } } } } } }, "responses": { "200": { "description": "Conversion completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Conversion failed" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/countries": { "get": { "tags": [ "Countries" ], "summary": "List all supported countries", "description": "Get a list of all EU countries with their e-invoicing mandate status, formats, and next deadlines.", "operationId": "listCountries", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "mandatory", "phased_rollout", "voluntary", "planned", "not_required" ] }, "description": "Filter by mandate status" }, { "name": "has_upcoming", "in": "query", "schema": { "type": "boolean" }, "description": "Only countries with deadlines in next 12 months" } ], "responses": { "200": { "description": "Country list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/countries/{code}": { "get": { "tags": [ "Countries" ], "summary": "Get country details", "description": "Get detailed e-invoicing requirements, formats, networks, and deadlines for a specific country.", "operationId": "getCountry", "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "ISO 3166-1 alpha-2 country code", "example": "DE" } ], "responses": { "200": { "description": "Country details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryDetailResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Country not found" } } } }, "/v1/rules/{country}": { "get": { "tags": [ "Countries" ], "summary": "Get validation rules for a country", "description": "Get the current validation rules applicable to a specific country, including version info and last update date.", "operationId": "getCountryRules", "parameters": [ { "name": "country", "in": "path", "required": true, "schema": { "type": "string" }, "example": "DE" } ], "responses": { "200": { "description": "Country rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RulesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Country not found" } } } }, "/v1/deadlines": { "get": { "tags": [ "Regulatory Intelligence" ], "summary": "Get compliance deadlines", "description": "Get upcoming e-invoicing compliance deadlines across EU countries.", "operationId": "getDeadlines", "parameters": [ { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Filter by country code" }, { "name": "months", "in": "query", "schema": { "type": "integer", "default": 12, "maximum": 60 }, "description": "Months ahead to look" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "b2b", "b2g", "b2c", "all" ] }, "description": "Filter by transaction type" } ], "responses": { "200": { "description": "Deadlines list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlinesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/requirements": { "get": { "tags": [ "Regulatory Intelligence" ], "summary": "Get trade lane requirements", "description": "Get e-invoicing requirements for a specific seller country to buyer country trade lane.", "operationId": "getRequirements", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Seller country code (ISO 3166-1 alpha-2)" }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Buyer country code (ISO 3166-1 alpha-2)" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "b2b", "b2g", "b2c" ] }, "description": "Transaction type" }, { "name": "asOf", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Check requirements as of this date (YYYY-MM-DD)" } ], "responses": { "200": { "description": "Requirements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequirementsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/compliance-score": { "post": { "tags": [ "Regulatory Intelligence" ], "summary": "Calculate compliance readiness score", "description": "Calculate your organization's compliance readiness across multiple EU markets. Available on Pro plan.", "operationId": "calculateComplianceScore", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "businessCountry", "customerCountries" ], "properties": { "businessCountry": { "type": "string", "description": "Your business country code" }, "customerCountries": { "type": "array", "items": { "type": "string" }, "description": "Customer country codes" }, "transactionTypes": { "type": "array", "items": { "type": "string", "enum": [ "b2b", "b2g", "b2c" ] }, "default": [ "b2b" ] }, "erpSystem": { "type": "string", "description": "ERP system identifier" }, "currentCapabilities": { "type": "object", "properties": { "canReceiveUBL": { "type": "boolean" }, "canSendUBL": { "type": "boolean" }, "hasPeppolId": { "type": "boolean" }, "hasXRechnungSupport": { "type": "boolean" } } } } } } } }, "responses": { "200": { "description": "Compliance score", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceScoreResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Requires Pro plan" } } } }, "/v1/changes": { "get": { "tags": [ "Regulatory Intelligence" ], "summary": "Get regulatory changes", "description": "Get regulatory changes since a specified date. Use this to monitor for updates that may affect your validation rules.", "operationId": "getChanges", "parameters": [ { "name": "since", "in": "query", "required": true, "schema": { "type": "string", "format": "date" }, "description": "Get changes since this date (YYYY-MM-DD)", "example": "2025-01-01" }, { "name": "countries", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated country codes", "example": "DE,FR,BE" }, { "name": "types", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated change types: deadline_change, format_update, mandate_change, penalty_update, clarification" } ], "responses": { "200": { "description": "Changes list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangesResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/errors": { "get": { "tags": [ "Reference Data" ], "summary": "List validation error codes", "description": "List all validation error codes with optional filtering. This is a public endpoint — no authentication required.", "operationId": "listErrors", "security": [], "parameters": [ { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Filter by country code" }, { "name": "format", "in": "query", "schema": { "type": "string" }, "description": "Filter by format (UBL, XRechnung, etc.)" }, { "name": "severity", "in": "query", "schema": { "type": "string", "enum": [ "error", "warning", "info" ] } }, { "name": "codeLists", "in": "query", "schema": { "type": "boolean" }, "description": "Include code lists in response" } ], "responses": { "200": { "description": "Error codes list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorsListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/errors/{ruleId}": { "get": { "tags": [ "Reference Data" ], "summary": "Get error code details", "description": "Get detailed information for a specific validation error code. This is a public endpoint — no authentication required.", "operationId": "getErrorDetail", "security": [], "parameters": [ { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Error rule ID", "example": "BR-01" } ], "responses": { "200": { "description": "Error code details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailResponse" } } } }, "404": { "description": "Error code not found" } } } }, "/v1/facts/search": { "get": { "tags": [ "Reference Data" ], "summary": "Search compliance facts", "description": "Search for compliance facts across countries. This is a public endpoint — no authentication required.", "operationId": "searchFacts", "security": [], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query" }, { "name": "country", "in": "query", "schema": { "type": "string" }, "description": "Filter by country code" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 10, "maximum": 50 } } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FactsSearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/facts/{country}": { "get": { "tags": [ "Reference Data" ], "summary": "Get country compliance facts", "description": "Get all compliance facts for a country. Supports JSON, Markdown, and plain text output. This is a public endpoint — no authentication required.", "operationId": "getCountryFacts", "security": [], "parameters": [ { "name": "country", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country code" }, { "name": "topic", "in": "query", "schema": { "type": "string" }, "description": "Filter by topic" }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "markdown", "text" ], "default": "json" } } ], "responses": { "200": { "description": "Country facts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountryFactsResponse" } }, "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v2/validate": { "post": { "tags": [ "Validation" ], "summary": "Validate an invoice (v2, fixability-enriched)", "operationId": "validateV2", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "xml" ], "properties": { "xml": { "type": "string", "description": "Invoice XML (UBL, CII, XRechnung, Peppol BIS, Factur-X)" }, "fileName": { "type": "string" }, "webhookUrl": { "type": "string", "format": "uri" }, "options": { "type": "object", "properties": { "ruleset_versions": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Pin ruleset versions, e.g. {\"peppol-bis\": \"3.0.17\"}" } } } } } } } }, "responses": { "200": { "description": "Validation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2ValidateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v2/validate-and-fix": { "post": { "tags": [ "Remediation" ], "summary": "Validate, surgically fix, re-validate — one call", "description": "Counts as 2 validations against the quota. Instant test keys (`POST /api/developers/instant-key`) can call this 10 times within an hour.", "operationId": "validateAndFixV2", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "xml" ], "properties": { "xml": { "type": "string" }, "fileName": { "type": "string" }, "autoFix": { "type": "boolean", "default": true }, "remediation_policy": { "type": "string", "enum": [ "safe", "none" ], "description": "`none` = validate only" }, "generate_evidence_pack": { "type": "boolean", "description": "Inline a signed evidence pack in the response" } } } } } }, "responses": { "200": { "description": "Pipeline completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2ValidateAndFixResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/QuotaExceeded" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/usage": { "get": { "tags": [ "Account" ], "summary": "Current usage of the calling key", "description": "The counter the key is metered on — identical to the dashboard bar. Calling this endpoint does not consume a request.", "operationId": "getUsage", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Usage snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSnapshot" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No active live key for this account" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key (sk_live_* for production, sk_test_* for sandbox)" } }, "schemas": { "ValidationResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "validationRef": { "type": "string", "description": "Unique validation reference ID" }, "isValid": { "type": "boolean" }, "format": { "type": "string", "description": "Detected format (ubl, cii, xrechnung, etc.)" }, "formatVersion": { "type": "string" }, "rulesetsApplied": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "pinned": { "type": "boolean" }, "latestAvailable": { "type": "string" }, "deprecationWarning": { "type": "string" } } } }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationIssue" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationIssue" } }, "metadata": { "$ref": "#/components/schemas/InvoiceMetadata" } } }, "meta": { "type": "object", "properties": { "validationRef": { "type": "string" }, "processingTimeMs": { "type": "integer" } } } } }, "ValidationIssue": { "type": "object", "properties": { "code": { "type": "string", "description": "Rule ID (e.g. BR-01, UBL-CR-001)" }, "message": { "type": "string" }, "location": { "type": "string", "description": "XPath location in the invoice" }, "suggestion": { "type": "string", "description": "How to fix this issue" } } }, "InvoiceMetadata": { "type": "object", "properties": { "invoiceNumber": { "type": "string" }, "issueDate": { "type": "string" }, "currency": { "type": "string" }, "sellerName": { "type": "string" }, "sellerVat": { "type": "string" }, "sellerCountry": { "type": "string" }, "buyerName": { "type": "string" }, "buyerVat": { "type": "string" }, "buyerCountry": { "type": "string" }, "totalAmount": { "type": "string" }, "taxAmount": { "type": "string" } } }, "BatchValidationResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "batchId": { "type": "string" }, "totalCount": { "type": "integer" }, "validCount": { "type": "integer" }, "invalidCount": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "validationRef": { "type": "string" }, "isValid": { "type": "boolean" }, "errorCount": { "type": "integer" }, "warningCount": { "type": "integer" }, "format": { "type": "string" } } } } } } } }, "FixResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "fixed_xml": { "type": "string" }, "applied_fixes": { "type": "array", "items": { "$ref": "#/components/schemas/FixResult" } }, "safe_fixer_fixes": { "type": "array", "items": { "$ref": "#/components/schemas/FixResult" } }, "failed_fixes": { "type": "array", "items": { "$ref": "#/components/schemas/FixResult" } }, "remaining_errors": { "type": "array", "items": { "type": "object" } }, "stats": { "type": "object", "properties": { "autoFixable": { "type": "integer" }, "inputRequired": { "type": "integer" }, "blocked": { "type": "integer" }, "safeFallbackFixCount": { "type": "integer" }, "totalFixesApplied": { "type": "integer" } } }, "diff": { "type": "string" }, "is_compliant": { "type": "boolean" }, "is_billable": { "type": "boolean" }, "engine": { "type": "string" } } }, "meta": { "type": "object", "properties": { "flow_id": { "type": "string" }, "duration_ms": { "type": "number" } } } } }, "FixResult": { "type": "object", "properties": { "error_code": { "type": "string" }, "success": { "type": "boolean" }, "operation": { "type": "string" }, "target_xpath": { "type": "string" }, "before_value": { "type": "string" }, "after_value": { "type": "string" }, "confidence": { "type": "number" }, "error_message": { "type": "string" } } }, "FixWithInputResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "fixed_xml": { "type": "string" }, "applied_fixes": { "type": "array", "items": { "$ref": "#/components/schemas/FixResult" } }, "failed_fixes": { "type": "array", "items": { "$ref": "#/components/schemas/FixResult" } }, "remaining_errors": { "type": "array", "items": { "type": "string" } }, "stats": { "type": "object", "properties": { "applied": { "type": "integer" }, "failed": { "type": "integer" }, "skipped": { "type": "integer" } } }, "is_compliant": { "type": "boolean" }, "is_billable": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "flow_id": { "type": "string" }, "duration_ms": { "type": "number" } } } } }, "UsageResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } }, "usage": { "type": "object", "properties": { "flows_used": { "type": "integer" }, "flows_limit": { "type": "integer" }, "flows_remaining": { "type": "integer" }, "percentage": { "type": "integer" } } }, "subscription": { "type": "object", "properties": { "tier": { "type": "string" }, "status": { "type": "string" }, "plan_name": { "type": "string" }, "evidence_pack": { "type": "boolean" } } }, "history": { "type": "object", "properties": { "today": { "type": "integer" }, "this_week": { "type": "integer" }, "last_month": { "type": "integer" }, "total": { "type": "integer" } } }, "resets_at": { "type": "string" } } } } }, "SignedEvidencePack": { "type": "object", "properties": { "evidencePackId": { "type": "string" }, "verificationCode": { "type": "string" }, "verifyUrl": { "type": "string", "format": "uri" }, "data": { "type": "object", "properties": { "evidencePackId": { "type": "string" }, "version": { "type": "string" }, "validatedAt": { "type": "string", "format": "date-time" }, "issuedAt": { "type": "string", "format": "date-time" }, "documentHash": { "type": "string" }, "documentSize": { "type": "integer" }, "documentFormat": { "type": "string" }, "engineVersion": { "type": "string" }, "rulesets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" } } } }, "result": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errorCount": { "type": "integer" }, "warningCount": { "type": "integer" } } }, "invoiceMetadata": { "$ref": "#/components/schemas/InvoiceMetadata" } } }, "proof": { "type": "object", "properties": { "algorithm": { "type": "string" }, "keyId": { "type": "string" }, "signature": { "type": "string" }, "signedAt": { "type": "string", "format": "date-time" }, "publicKeyUrl": { "type": "string", "format": "uri" } } } } }, "EvidencePackListResponse": { "type": "object", "properties": { "evidence_packs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "validation_id": { "type": "string" }, "document_hash": { "type": "string" }, "result": { "type": "string", "enum": [ "passed", "failed" ] }, "invoice_number": { "type": "string" }, "supplier_name": { "type": "string" }, "format_detected": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "verification_url": { "type": "string", "format": "uri" } } } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_more": { "type": "boolean" } } } } }, "VerificationResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "verified": { "type": "boolean" }, "evidencePackId": { "type": "string" }, "checks": { "type": "object", "properties": { "exists": { "type": "boolean" }, "notExpired": { "type": "boolean" }, "signatureValid": { "type": "boolean" } } }, "details": { "type": "object", "properties": { "issuedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "validationResult": { "type": "string", "enum": [ "PASSED", "FAILED" ] }, "documentHash": { "type": "string" }, "format": { "type": "string" }, "rulesets": { "type": "array", "items": { "type": "string" } } } }, "invoiceMetadata": { "$ref": "#/components/schemas/InvoiceMetadata" } } }, "ConversionResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "conversionId": { "type": "string" }, "sourceFormat": { "type": "object", "properties": { "detected": { "type": "string" }, "version": { "type": "string" } } }, "targetFormat": { "type": "string" }, "result": { "type": "string", "description": "Base64-encoded converted XML" }, "validation": { "type": "object", "properties": { "valid": { "type": "boolean" }, "errorCount": { "type": "integer" }, "warningCount": { "type": "integer" }, "issues": { "type": "array", "items": { "type": "object" } } } }, "metadata": { "$ref": "#/components/schemas/InvoiceMetadata" }, "processingTimeMs": { "type": "integer" } } } } }, "CountryListResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "flag": { "type": "string" }, "b2g_status": { "type": "string" }, "b2b_status": { "type": "string" }, "next_deadline": { "type": "string", "format": "date" }, "primary_format": { "type": "string" }, "last_updated": { "type": "string", "format": "date-time" }, "confidence": { "type": "string" } } } }, "total": { "type": "integer" } } } } }, "CountryDetailResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "e_invoicing": { "type": "object", "properties": { "b2g": { "type": "object" }, "b2b": { "type": "object" } } }, "formats": { "type": "object" }, "networks": { "type": "object" }, "upcoming_deadlines": { "type": "array", "items": { "type": "object" } }, "rulesets": { "type": "array", "items": { "type": "object" } }, "last_updated": { "type": "string", "format": "date-time" }, "confidence": { "type": "string" } } } } }, "RulesResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "rulesVersion": { "type": "string" }, "lastUpdated": { "type": "string", "format": "date" }, "rules": { "type": "object", "properties": { "total": { "type": "integer" }, "byCategory": { "type": "object" }, "countrySpecificRules": { "type": "array", "items": { "type": "object" } } } } } } } }, "DeadlinesResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "country": { "type": "string" }, "monthsAhead": { "type": "integer" }, "transactionType": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "totalDeadlines": { "type": "integer" } } }, "summary": { "type": "object", "properties": { "criticalCount": { "type": "integer" }, "within90Days": { "type": "integer" }, "within365Days": { "type": "integer" } } }, "deadlines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "format": "date" }, "country": { "type": "string" }, "countryName": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "impact": { "type": "string" }, "daysUntil": { "type": "integer" }, "isPast": { "type": "boolean" }, "isUrgent": { "type": "boolean" } } } } } } } }, "RequirementsResponse": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "fromCountry": { "type": "string" }, "toCountry": { "type": "string" }, "transactionType": { "type": "string" }, "asOfDate": { "type": "string", "format": "date" }, "dataVersion": { "type": "string" }, "lastUpdated": { "type": "string", "format": "date-time" } } }, "requirements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "country": { "type": "string" }, "type": { "type": "string" }, "direction": { "type": "string" }, "requirement": { "type": "string" }, "description": { "type": "string" }, "effectiveDate": { "type": "string", "format": "date" }, "format": { "type": "string" }, "channel": { "type": "string" }, "source": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "tags": { "type": "array", "items": { "type": "string" } } } } }, "summary": { "type": "string" } } }, "ComplianceScoreResponse": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "apiVersion": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" } } }, "input": { "type": "object" }, "score": { "type": "object", "properties": { "value": { "type": "number", "description": "Percentage score" }, "earned": { "type": "number" }, "maximum": { "type": "number" }, "grade": { "type": "string" } } }, "summary": { "type": "string" }, "gaps": { "type": "object" }, "strengths": { "type": "object" }, "roadmap": { "type": "object" }, "byCountry": { "type": "object" } } }, "ChangesResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" }, "summary": { "type": "object", "properties": { "totalChanges": { "type": "integer" }, "byUrgency": { "type": "object" }, "byType": { "type": "object" } } }, "changes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "country": { "type": "string" }, "type": { "type": "string", "enum": [ "deadline_change", "format_update", "mandate_change", "penalty_update", "clarification" ] }, "urgency": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "summary": { "type": "string" }, "effectiveDate": { "type": "string", "format": "date" }, "actionRequired": { "type": "string" } } } }, "rulesUpdated": { "type": "array", "items": { "type": "object" } } } } } }, "ErrorsListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "ruleId": { "type": "string" }, "title": { "type": "string" }, "severity": { "type": "string" }, "applicableFormats": { "type": "array", "items": { "type": "string" } }, "applicableCountries": { "type": "array", "items": { "type": "string" } } } } }, "codeLists": { "type": "object" }, "_links": { "type": "object", "properties": { "self": { "type": "string" }, "documentation": { "type": "string" } } } } }, "ErrorDetailResponse": { "type": "object", "properties": { "ruleId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "severity": { "type": "string" }, "resolution": { "type": "string" }, "xpath": { "type": "string" }, "example": { "type": "string" }, "applicableFormats": { "type": "array", "items": { "type": "string" } }, "applicableCountries": { "type": "array", "items": { "type": "string" } }, "codeList": { "type": "object" }, "_links": { "type": "object" } } }, "FactsSearchResponse": { "type": "object", "properties": { "query": { "type": "string" }, "resultsCount": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "countryName": { "type": "string" }, "claim": { "type": "string" }, "claimType": { "type": "string" }, "effectiveDate": { "type": "string", "format": "date" }, "source": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri" }, "lastVerified": { "type": "string", "format": "date" } } } } } }, "CountryFactsResponse": { "type": "object", "properties": { "country": { "type": "string" }, "countryName": { "type": "string" }, "topic": { "type": "string" }, "factsCount": { "type": "integer" }, "lastUpdated": { "type": "string", "format": "date" }, "meta": { "type": "object", "properties": { "source": { "type": "string" }, "sourceUrl": { "type": "string" }, "disclaimer": { "type": "string" } } }, "facts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "country": { "type": "string" }, "topic": { "type": "string" }, "subtopic": { "type": "string" }, "claim": { "type": "string" }, "claimType": { "type": "string" }, "confidence": { "type": "string" }, "effectiveDate": { "type": "string", "format": "date" }, "lastVerified": { "type": "string", "format": "date" }, "source": { "type": "object" }, "tags": { "type": "array", "items": { "type": "string" } } } } }, "summary": { "type": "string" } } }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } } }, "V2Issue": { "type": "object", "required": [ "code", "severity", "title", "message", "fixable" ], "properties": { "code": { "type": "string", "example": "BR-CO-10" }, "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "title": { "type": "string" }, "message": { "type": "string" }, "location": { "type": "string", "description": "XPath of the offending node" }, "suggestion": { "type": "string" }, "fixable": { "type": "boolean" }, "fixType": { "type": "string", "enum": [ "auto", "confirm", "input", "blocked" ] }, "fixConfidence": { "type": "number", "minimum": 0, "maximum": 1 } } }, "V2FixSummary": { "type": "object", "properties": { "totalIssues": { "type": "integer" }, "autoFixable": { "type": "integer" }, "needsInput": { "type": "integer" }, "blocked": { "type": "integer" }, "unknown": { "type": "integer" }, "canAutoFixAll": { "type": "boolean" } } }, "V2InvoiceMetadata": { "type": "object", "properties": { "invoiceNumber": { "type": "string" }, "issueDate": { "type": "string" }, "currency": { "type": "string" }, "sellerName": { "type": "string" }, "sellerVat": { "type": "string" }, "sellerCountry": { "type": "string" }, "buyerName": { "type": "string" }, "buyerVat": { "type": "string" }, "buyerCountry": { "type": "string" }, "totalAmount": { "type": "string" }, "taxAmount": { "type": "string" } } }, "V2ResponseMeta": { "type": "object", "properties": { "validationRef": { "type": "string" }, "processingTimeMs": { "type": "integer" }, "requestId": { "type": "string" }, "testMode": { "type": "boolean", "description": "Present (true) when the call used an sk_test_ key" } } }, "V2ValidateResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "required": [ "validationRef", "isValid", "issues", "_links" ], "properties": { "validationRef": { "type": "string" }, "isValid": { "type": "boolean" }, "format": { "type": "string", "nullable": true, "example": "UBL" }, "formatVersion": { "type": "string", "nullable": true }, "rulesetsApplied": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "pinned": { "type": "boolean" }, "latestAvailable": { "type": "string" }, "deprecationWarning": { "type": "string" } } } }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/V2Issue" } }, "fixSummary": { "$ref": "#/components/schemas/V2FixSummary", "nullable": true }, "metadata": { "$ref": "#/components/schemas/V2InvoiceMetadata" }, "_links": { "type": "object", "properties": { "self": { "type": "string" }, "fix": { "type": "string" }, "categorize": { "type": "string" } } } } }, "meta": { "$ref": "#/components/schemas/V2ResponseMeta" } } }, "V2ValidateAndFixResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "required": [ "validationRef", "originalValid", "remainingIssues", "metadata", "_links" ], "properties": { "validationRef": { "type": "string" }, "originalValid": { "type": "boolean", "description": "Whether the submitted XML already passed" }, "fixedValid": { "type": "boolean", "description": "Whether the returned fixedXml passes re-validation" }, "fixesApplied": { "type": "integer" }, "fixedXml": { "type": "string", "description": "Patched XML (surgical edits; financial fields are never touched)" }, "remainingIssues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "title": { "type": "string" }, "message": { "type": "string" } } } }, "fixSummary": { "$ref": "#/components/schemas/V2FixSummary", "nullable": true }, "metadata": { "$ref": "#/components/schemas/V2InvoiceMetadata" }, "flowId": { "type": "string", "description": "Absent for sk_test_ keys" }, "engine": { "type": "string", "enum": [ "orchestrator", "safe-fixer", "hybrid" ] }, "evidencePackUrl": { "type": "string" }, "evidencePack": { "$ref": "#/components/schemas/SignedEvidencePack" }, "_links": { "type": "object", "properties": { "self": { "type": "string" }, "fixWithInput": { "type": "string" }, "evidencePack": { "type": "string" } } } } }, "meta": { "$ref": "#/components/schemas/V2ResponseMeta" } } }, "UsageSnapshot": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "keyId": { "type": "string" }, "keyType": { "type": "string", "enum": [ "live", "test" ] }, "tier": { "type": "string" }, "metered": { "type": "boolean" }, "used": { "type": "integer" }, "included": { "type": "integer" }, "remaining": { "type": "integer" }, "percentage": { "type": "integer" }, "periodStart": { "type": "string", "nullable": true }, "periodEnd": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "usage_billing", "api_keys", "instant_key", "unmetered" ] }, "upgradeUrl": { "type": "string", "example": "/checkout/start?tier=pro" } } } } } }, "responses": { "BadRequest": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "BAD_REQUEST", "message": "The \"xml\" field must be a valid XML string" } } } } }, "Unauthorized": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid API key" } } } } }, "RateLimited": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Try again in 42 seconds.", "details": { "limit": 60, "remaining": 0, "resetAt": "2026-09-13T12:00:00.000Z" } } } } } }, "QuotaExceeded": { "description": "Metered allowance used up (Payment Required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": { "code": "QUOTA_EXCEEDED", "message": "Monthly quota exceeded. Upgrade your plan for more validations.", "details": { "used": 100, "limit": 100, "tier": "free", "upgradeUrl": "/checkout/start?tier=pro" } } } } } } } } }