{"openapi":"3.1.0","info":{"version":"1.0.0","title":"Space Invoices API","description":"REST API for invoice management, customer management, and accounting operations. Features include cursor-based pagination for efficient data navigation, flexible JSON querying with MongoDB-style operators, full-text search across multiple fields, and comprehensive metadata support for custom tracking.","contact":{"name":"Space Invoices API Support","email":"api@spaceinvoices.com"},"license":{"name":"Proprietary","url":"https://spaceinvoices.com/terms"}},"servers":[{"url":"https://eu.spaceinvoices.com","description":"Production server (EU)"},{"url":"http://localhost:3000","description":"Development server"}],"security":[{"Bearer":[]}],"tags":[{"name":"Activities","description":"Activity log for entity resources. Tracks actions like creation, updates, deletions, and custom events across all resource types. Read-only - activities are created automatically by the system."},{"name":"Advance Invoices","description":"Advance invoice management operations. Create, retrieve, and list advance invoices. Advance invoices are issued before goods/services are delivered to collect prepayment. When linked to a final invoice, the paid amount is applied as a payment."},{"name":"CreditNotes","description":"Credit note management operations.\nCreate, retrieve, and list credit notes with flexible querying.\nCredit notes are issued by Entities to Customers and contain line items with optional taxes.\nUnlike invoices, credit notes do not have a due date."},{"name":"Delivery Notes","description":"Delivery note management operations.\nCreate, retrieve, and list delivery notes with flexible querying.\nDelivery notes are shipping/packing documents issued by Entities to Customers and contain line items.\nSupports hide_prices mode for packing list output."},{"name":"Estimates","description":"Estimate management operations.\nCreate, retrieve, and list estimates with flexible querying.\nEstimates are issued by Entities to Customers and contain line items with optional taxes.\nEstimates represent proposed pricing and are valid until a specified date."},{"name":"Invoices","description":"Invoice management operations.\nCreate, retrieve, and list invoices with flexible querying.\nInvoices are issued by Entities to Customers and contain line items with optional taxes."},{"name":"Exports","description":"Export documents (invoices, estimates, credit notes) to Excel or CSV format.\nSupports date range filtering and query filters."},{"name":"Business Units","description":"Manage entity-owned business units used for document branding, defaults, and integrations."},{"name":"Customers","description":"Customer management for invoice recipients.\nStore customer details including address and tax information for use in invoice creation."},{"name":"Expenses","description":"Received supplier invoices and expense records."},{"name":"Entities","description":"Legal entity (business, organization) management. Entities are the core organizational unit that owns customers, invoices, and items."},{"name":"Entity Stats","description":"Flexible aggregation queries for entity data. Query counts, sums, averages across invoices, payments, customers, and more."},{"name":"Entity Users","description":"Manage user access to entities with role-based permissions (viewer, editor, admin)."},{"name":"Entity Invitations","description":"Manage entity user invitations - list, accept, cancel, resend."},{"name":"Entity API Keys","description":"Manage entity-scoped API keys (ek_* prefix) for userless access to entities."},{"name":"Items","description":"Product and service catalog management. Items can be referenced in invoices and include pricing and tax information."},{"name":"Financial Categories","description":"Entity-scoped reporting categories shared by saved items, document lines, revenue analytics, and future expense reporting."},{"name":"Taxes","description":"Tax rate management with support for historical rate changes. Each tax can have multiple rates with different valid_from dates to track rate changes over time."},{"name":"Users","description":"User authentication and profile operations. Users can access multiple entities and manage their account settings."},{"name":"Payments","description":"Payment management operations.\nRecord payments against outgoing documents and expenses.\nSupports partial payments, credit note applications, and automatic payment status updates."},{"name":"Upload","description":"File upload endpoints for images and documents. All uploads are scoped to entities."},{"name":"Files","description":"File metadata management.\nUpload and manage files (logos, signatures, attachments) associated with entities and documents."},{"name":"Email","description":"Email sending endpoints for sending invoices and documents. Automatically includes company logo from entity settings, generates public shareable invoice links, and optionally attaches PDFs."},{"name":"Payment Reminders","description":"Manual payment reminder emails for overdue customer invoices."},{"name":"FURS Settings","description":"Configure FURS fiscalization settings including numbering strategy and operator details"},{"name":"FURS Certificate","description":"Upload and manage the P12/PFX certificate required for FURS fiscalization"},{"name":"FURS Internal Act","description":"Download the Slovenian FURS internal act in PDF or DOCX format."},{"name":"FURS Premises","description":"Register and manage business premises (physical locations or movable units) for FURS fiscalization"},{"name":"FURS Devices","description":"Register and manage electronic devices (cash registers, POS terminals) for FURS fiscalization"},{"name":"FINA Settings","description":"Configure CIS (Croatia) fiscalization settings including operator OIB, PDV system, and numbering"},{"name":"FINA Certificate","description":"Upload and manage the P12/PFX certificate required for Croatian CIS fiscalization"},{"name":"FINA Premises","description":"Manage business premises for FINA fiscalization"},{"name":"FINA Devices","description":"Manage electronic devices within business premises"},{"name":"PT ATCUD Series","description":"Manage Portugal ATCUD series registrations used for PT numbering and SAF-T exports."},{"name":"PT SAF-T","description":"Generate Portugal SAF-T audit export files for PT entities."},{"name":"Transaction Type","description":"Determine transaction type and reverse charge applicability based on issuer and customer information.\nUses VIES (VAT Information Exchange System) validation internally for EU tax numbers."},{"name":"VIES","description":"**Deprecated:** Use the Transaction Type endpoint instead.\nVIES (VAT Information Exchange System) validation for EU tax numbers."},{"name":"Company Registry","description":"Public company registry data for autocomplete. Search companies from government registries (e.g., AJPES for Slovenia) to auto-fill customer details."},{"name":"Currency","description":"Currency conversion helpers for looking up exchange rates by currency pair and date."},{"name":"Tax Rate Estimates","description":"Country-scoped tax-rate estimate lookups. Estimates are helper data only and do not replace merchant tax compliance review."},{"name":"Tax Reports","description":"Generate Slovenian tax report exports, including KIR and yearly eDavki filings."},{"name":"Recurring Invoices","description":"Recurring invoice schedule management.\nAutomate invoice generation on a daily, weekly, monthly, or yearly schedule using an existing invoice as a template."},{"name":"Revenue Recognition","description":"Deferred revenue and accrued revenue reporting generated from finalized sales documents and their service periods."},{"name":"Webhooks","description":"Webhook endpoint management for receiving real-time event notifications. Configure URLs, select events, and monitor delivery status.\n\n## Event types\n\nSubscribe to any combination of these events:\n\n| Category | Events |\n|----------|--------|\n| **Invoices** | `invoice.created` `invoice.updated` `invoice.sent` `invoice.paid` `invoice.overdue` `invoice.cancelled` |\n| **Customers** | `customer.created` `customer.updated` `customer.deleted` |\n| **Payments** | `payment.received` `payment.failed` |\n| **Items** | `item.created` `item.updated` `item.deleted` `item.restored` |\n| **Estimates** | `estimate.created` `estimate.sent` `estimate.accepted` `estimate.rejected` |\n| **Credit notes** | `credit_note.created` `credit_note.issued` |\n| **Advance invoices** | `advance_invoice.created` `advance_invoice.paid` `advance_invoice.applied` |\n\n## Payload format\n\nEvery webhook delivery sends a JSON body with this structure:\n\n```json\n{\n  \"event\": \"invoice.created\",\n  \"data\": { ... },\n  \"timestamp\": \"2024-01-15T10:30:00.000Z\"\n}\n```\n\n## Delivery headers\n\nEach delivery includes these headers:\n\n| Header | Description |\n|--------|-------------|\n| `X-Webhook-Signature` | HMAC-SHA256 signature: `sha256=<hex>` |\n| `X-Webhook-Timestamp` | Unix timestamp (seconds) when the payload was signed |\n| `X-Webhook-Event` | Event type (e.g. `invoice.created`) |\n| `X-Webhook-Delivery` | Unique delivery attempt ID |\n| `X-Webhook-Id` | Webhook endpoint ID |\n| `User-Agent` | `SpaceInvoices-Webhook/1.0` |\n\n## Verifying signatures\n\nSignatures use **HMAC-SHA256**. To verify:\n\n1. Get the raw request body (do not parse it first)\n2. Compute `HMAC-SHA256(secret, body)` using your webhook secret\n3. Compare the hex digest with the value after `sha256=` in `X-Webhook-Signature`\n\n```javascript\nconst crypto = require('crypto');\n\nfunction verifySignature(secret, payload, signature) {\n  const expected = crypto\n    .createHmac('sha256', secret)\n    .update(payload)\n    .digest('hex');\n  return signature === `sha256=${expected}`;\n}\n```\n\n## Retry policy\n\nFailed deliveries are retried up to **5 attempts** with exponential backoff:\n\n| Attempt | Delay |\n|---------|-------|\n| 1 | Immediate |\n| 2 | 1 minute |\n| 3 | 5 minutes |\n| 4 | 30 minutes |\n| 5 | 2 hours |\n\nWebhooks are **automatically disabled** after all retry attempts are exhausted, and an email notification is sent to the entity owner.\n\nHTTP status codes 400, 401, 403, 404, 405, and 410 are treated as **permanent failures** and are not retried."},{"name":"Account Webhooks","description":"Account-scoped webhook endpoint management for white-label subscription lifecycle events."},{"name":"White Labels","description":"White-label configuration for multi-product support."},{"name":"White-Label Subscriptions","description":"Entity-level subscription management for white-label products."},{"name":"Stripe App","description":"Stripe Marketplace App integration for creating compliant invoices from Stripe data."},{"name":"Order Integrations","description":"Manage connections to external e-commerce platforms.\nConnect Shopify, WooCommerce, or other platforms to automatically receive and process orders into invoices."},{"name":"Orders","description":"Order management for e-commerce integrations.\nReceive, store, and process orders from external platforms into invoices."},{"name":"E-Invoicing","description":"Send invoices and credit notes electronically over the Peppol network."},{"name":"e-SLOG","description":"e-SLOG 2.0 (Slovenian electronic invoice) operations.\nDocuments can be validated and exported as native e-SLOG XML in the official `urn:eslog:2.00` format.\nOnly available for Slovenian entities (country_code = 'SI')."},{"name":"UJP","description":"Slovenian UJP e-invoice package operations. The package endpoint generates native e-SLOG XML, a required UJP envelope, a tar.gz attachment package, and PDF visualization files for provider or UJP B2B exchange workflows."}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","description":"Bearer Token Authentication in the form of Authorization: Bearer {token}"}},"schemas":{"Invoice":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"number":{"type":"string","maxLength":100},"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","format":"date-time","description":"Date the invoice was created (ISO 8601 datetime at midnight UTC)"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/BusinessUnitSnapshot"},{"type":"null"}],"description":"Frozen business-unit snapshot used for stable rendering and historical accuracy."},"customer_id":{"type":["string","null"],"maxLength":36},"customer":{"anyOf":[{"$ref":"#/components/schemas/DocumentCustomer"},{"type":"null"}],"description":"Customer information snapshot stored on the document. Null means no customer. When present, known customer fields are returned with null for omitted values."},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"$ref":"#/components/schemas/DocumentTranslations"},"total":{"type":"number","description":"Document total before tax in the currency's major unit. For EUR, `29.90` means €29.90, not 2,990 cents."},"total_with_tax":{"type":"number","description":"Document total after tax in the currency's major unit. For EUR, `29.90` means €29.90, not 2,990 cents."},"total_discount":{"type":"number","description":"Document discount total in the currency's major unit, stored as a net-equivalent amount for compatibility. In `b2b_standard`, this is the net value of line-item discounts applied before tax. In `b2c_gross_discount`, gross discounts are converted back to their net-equivalent value here. 0 when no discounts applied."},"creation_source":{"$ref":"#/components/schemas/CreationSource"},"calculation_mode":{"type":"string","enum":["b2b_standard","b2c_gross_discount"],"description":"Resolved calculation mode used for this document. Stored on the document so recalculation and rendering remain stable even if entity defaults change later.","example":"b2b_standard"},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"},"description":"Applied taxes summary"},"currency_code":{"type":"string","maxLength":3},"entity_id":{"type":"string","maxLength":36},"date_year":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"shareable_id":{"type":["string","null"],"maxLength":100},"voided_at":{"type":["string","null"],"format":"date-time"},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export",null],"description":"Transaction type for VAT purposes (domestic, intra_eu_b2b, intra_eu_b2c, export). Always determined based on issuer/customer countries."},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"exchange_rate":{"anyOf":[{"$ref":"#/components/schemas/ExchangeRate"},{"type":"null"}],"description":"Currency exchange rate information if conversion was applied"},"total_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"total_with_tax_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"rounding_correction":{"type":["number","null"],"description":"Rounding correction in the currency's major unit, applied to reconcile differences between calculated total_with_tax and expected_total_with_tax. Only present when expected_total_with_tax was provided during creation."},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogData"},{"type":"null"}],"description":"e-SLOG 2.0 validation data for Slovenian electronic invoices. Only applicable when entity.country_code = 'SI' and eslog validation is enabled."},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"vies":{"anyOf":[{"$ref":"#/components/schemas/ViesDocumentData"},{"type":"null"},{"type":"null"}],"description":"VIES validation info including any warnings and skipped indicator for audit trail"},"deleted_at":{"type":["string","null"],"format":"date-time","description":"Timestamp when the document was soft-deleted. Null if not deleted."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"date_due":{"type":["string","null"],"format":"date-time","description":"Date the invoice is due (ISO 8601 datetime at midnight UTC)"},"total_paid":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_due":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"paid_in_full":{"type":"boolean"},"furs":{"anyOf":[{"$ref":"#/components/schemas/FursFiscalizationResponse"},{"type":"null"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/FinaFiscalizationResponse"},{"type":"null"}]},"pt":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"xrechnung":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingData"},{"type":"null"}],"description":"Server-managed German XRechnung validation data stored on invoices. Only applicable when entity.country_code = 'DE' and XRechnung is enabled. Buyer reference / Leitweg-ID input is stored on customer.e_invoicing.buyer_reference."},"zugferd":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingData"},{"type":"null"}],"description":"Server-managed German ZUGFeRD/Factur-X validation data stored on invoices. Only applicable when entity.country_code = 'DE' and ZUGFeRD is enabled. Buyer reference / Leitweg-ID input is stored on customer.e_invoicing.buyer_reference."},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpData"},{"type":"null"}],"description":"UJP package validation data for Slovenian invoice exports. Only applicable when entity.country_code = 'SI' and UJP validation is enabled."},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceItem"}},"document_relations":{"type":"array","items":{"$ref":"#/components/schemas/DocumentRelation"}}},"required":["id","number","is_draft","date","issuer","translations","total","total_with_tax","total_discount","creation_source","calculation_mode","taxes","currency_code","entity_id","date_year","created_at","updated_at","total_paid","total_due","paid_in_full","items"],"description":"Invoice document with fiscalization support"},"DocumentEntity":{"type":"object","properties":{"name":{"type":["string","null"]},"unit_name":{"type":["string","null"],"deprecated":true,"description":"Deprecated compatibility field. This value is no longer used for business-unit rendering; use `business_unit.name` on the document instead."},"email":{"type":["string","null"],"maxLength":255},"address":{"type":["string","null"]},"address_2":{"type":["string","null"]},"post_code":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]},"country_code":{"type":["string","null"],"maxLength":2},"tax_number":{"type":["string","null"]},"tax_number_2":{"type":["string","null"]},"company_number":{"type":["string","null"]},"phone":{"type":["string","null"]},"peppol_id":{"type":["string","null"]},"peppol_scheme_id":{"type":["string","null"]},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentEInvoicingCustomerData"},{"type":"null"}]},"bank_accounts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/EntityBankAccount"}},"is_end_consumer":{"type":["boolean","null"]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpCustomerData"},{"type":"null"}]},"bank_account":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["iban","us_domestic","uk_domestic","other"],"default":"iban","description":"Account type determines which fields are used","example":"iban"},"name":{"type":["string","null"],"description":"Display name for this account. Falls back to account number if not set","example":"Main Business Account"},"bank_name":{"type":["string","null"],"description":"Bank name","example":"NLB d.d."},"iban":{"type":["string","null"],"description":"IBAN (for type=iban)","example":"SI56012345678901234"},"account_number":{"type":["string","null"],"description":"Account number (for us_domestic, uk_domestic, other)","example":"123456789"},"bic":{"type":["string","null"],"description":"BIC/SWIFT code for international transfers","example":"LJBASI2X"},"routing_number":{"type":["string","null"],"description":"US ABA routing number (for type=us_domestic)","example":"021000021"},"sort_code":{"type":["string","null"],"description":"UK sort code (for type=uk_domestic)","example":"12-34-56"}}}},"description":"Document issuer (entity) information"},"DocumentEInvoicingCustomerData":{"type":"object","properties":{"buyer_reference":{"type":["string","null"],"description":"Canonical EN 16931 BT-10 buyer reference stored on the document customer snapshot. For German public-sector recipients, enter the Leitweg-ID here. For German B2B recipients this is optional unless the buyer requires it. Do not send a separate leitweg_id, routing_id, or top-level buyer_reference field.","example":"991-12345-67"}},"description":"Customer e-invoicing data copied into the document customer snapshot. These fields are buyer/customer document data, not German validation state."},"EntityBankAccount":{"type":"object","properties":{"type":{"type":"string","enum":["iban","us_domestic","uk_domestic","other"],"default":"iban","description":"Account type determines which fields are used","example":"iban"},"name":{"type":["string","null"],"description":"Display name for this account. Falls back to account number if not set","example":"Main Business Account"},"bank_name":{"type":["string","null"],"description":"Bank name","example":"NLB d.d."},"iban":{"type":["string","null"],"description":"IBAN (for type=iban)","example":"SI56012345678901234"},"account_number":{"type":["string","null"],"description":"Account number (for us_domestic, uk_domestic, other)","example":"123456789"},"bic":{"type":["string","null"],"description":"BIC/SWIFT code for international transfers","example":"LJBASI2X"},"routing_number":{"type":["string","null"],"description":"US ABA routing number (for type=us_domestic)","example":"021000021"},"sort_code":{"type":["string","null"],"description":"UK sort code (for type=uk_domestic)","example":"12-34-56"},"is_default":{"type":["boolean","null"],"description":"Whether this is the default account for new invoices","example":true}}},"UjpCustomerData":{"type":"object","properties":{"receiver_name":{"type":["string","null"],"minLength":1,"description":"UJP envelope recipient name. If omitted, package generation falls back to the document customer name.","example":"Obcina Ljubljana"},"receiver_identifier":{"type":["string","null"],"minLength":1,"description":"Optional recipient tax number or identifier override for the UJP envelope. If omitted, package generation falls back to the document customer tax number.","example":"12345678"},"receiver_agent":{"type":["string","null"],"minLength":1,"description":"Recipient BIC for the UJP envelope. Public budget users normally use UJPLSI2DICL.","example":"UJPLSI2DICL"},"receiver_mailbox":{"type":["string","null"],"minLength":1,"description":"Recipient IBAN/TRR mailbox for the UJP envelope.","example":"SI56011006030707507"}},"additionalProperties":false,"description":"Optional Slovenian UJP recipient routing data stored on customers and copied into document customer snapshots."},"BusinessUnitSnapshot":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"deleted_at":{"type":["string","null"],"format":"date-time"},"address":{"type":["string","null"]},"address_2":{"type":["string","null"]},"post_code":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]},"country_code":{"type":["string","null"],"minLength":2,"maxLength":2},"email":{"type":["string","null"],"format":"email"},"phone":{"type":["string","null"]},"website":{"type":["string","null"],"format":"uri"},"settings":{"$ref":"#/components/schemas/BusinessUnitSettings"},"logo_url":{"type":["string","null"],"format":"uri"},"signature_url":{"type":["string","null"],"format":"uri"}},"required":["id","name","settings"],"description":"Frozen business-unit snapshot persisted on documents for rendering and history."},"BusinessUnitSettings":{"type":"object","properties":{"pdf_template":{"type":["string","null"],"enum":["modern","classic","condensed","minimal","fashion","timeless_modern_full_data",null],"description":"Default PDF template for document rendering. Defaults to 'modern' if not set.","example":"modern"},"primary_color":{"type":["string","null"],"pattern":"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"},"logo_scale_percent":{"type":["integer","null"],"minimum":30,"maximum":100,"description":"Scale the PDF logo size as a percentage of the template default size. 100 keeps the original size.","example":70},"email_defaults":{"type":["object","null"],"properties":{"invoice_subject":{"type":["string","null"],"description":"Default subject line for invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_due_date}, {document_total}, {document_currency}","example":"Invoice {document_number} from {entity_name}"},"invoice_body":{"type":["string","null"],"description":"Default body text for invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_due_date}, {document_total}, {document_currency}","example":"Please find invoice {document_number} attached.\nDue date: {document_due_date}."},"estimate_subject":{"type":["string","null"],"description":"Default subject line for estimate emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_valid_until}, {document_total}, {document_currency}","example":"Estimate {document_number} from {entity_name}"},"estimate_body":{"type":["string","null"],"description":"Default body text for estimate emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_valid_until}, {document_total}, {document_currency}","example":"Please find estimate {document_number} attached.\nValid until: {document_valid_until}."},"credit_note_subject":{"type":["string","null"],"description":"Default subject line for credit note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Credit note {document_number} from {entity_name}"},"credit_note_body":{"type":["string","null"],"description":"Default body text for credit note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Please find credit note {document_number} attached."},"advance_invoice_subject":{"type":["string","null"],"description":"Default subject line for advance invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Advance invoice {document_number} from {entity_name}"},"advance_invoice_body":{"type":["string","null"],"description":"Default body text for advance invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Please find advance invoice {document_number} attached."},"delivery_note_subject":{"type":["string","null"],"description":"Default subject line for delivery note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Delivery note {document_number} from {entity_name}"},"delivery_note_body":{"type":["string","null"],"description":"Default body text for delivery note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Please find delivery note {document_number} attached."}}},"translations":{"anyOf":[{"$ref":"#/components/schemas/EntitySettingsTranslations"},{"type":"null"}],"description":"Translated default document-facing settings keyed by full supported locales. Used when new documents inherit default texts and when document defaults are rendered in an explicit non-default language."},"default_invoice_note":{"type":["string","null"],"description":"Default note for new invoices. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Payment due by {document_due_date}. Please reference invoice {document_number} when making payment."},"default_invoice_payment_terms":{"type":["string","null"],"description":"Default payment terms for new invoices. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Please remit payment using the bank details shown on the document."},"default_estimate_note":{"type":["string","null"],"description":"Default note for new estimates. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_valid_until}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"This estimate is valid until {document_valid_until}."},"default_estimate_payment_terms":{"type":["string","null"],"description":"Default payment terms for new estimates. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_valid_until}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Payment due upon acceptance."},"default_credit_note_note":{"type":["string","null"],"description":"Default note for new credit notes. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Credit note for invoice {document_number}."},"default_credit_note_payment_terms":{"type":["string","null"],"description":"Default payment terms for new credit notes. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Credit will be applied to your account."},"default_advance_invoice_note":{"type":["string","null"],"description":"Default note for new advance invoices. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Advance payment requested for {document_number}."},"default_delivery_note_note":{"type":["string","null"],"description":"Default note for new delivery notes. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Goods delivered under delivery note {document_number}."},"document_footer":{"type":["string","null"],"maxLength":500,"description":"Footer text for PDF documents. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"{entity_name} | Due Date: {document_due_date} | Invoice #{document_number}"},"default_document_signature":{"type":["string","null"],"description":"Default signature text for all new documents. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"{entity_name}"},"bank_accounts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/EntityBankAccount"},"description":"Bank accounts for receiving payments. The first account with is_default=true (or first in list) is used for new invoices."},"delivery_note_hide_prices":{"type":["boolean","null"],"description":"Default hide_prices setting for new delivery notes. When true, prices and totals are hidden (packing list mode).","example":false},"credit_note_negative_values":{"type":["boolean","null"],"description":"When true (default), credit note PDFs display line item quantities and totals as negative values while keeping prices positive. Zero quantities and totals stay unsigned. Set to false to show quantities and totals as positive.","example":true},"show_payment_amounts":{"type":["boolean","null"],"description":"When true, rendered document payment/refund sections show the payment amount next to each payment type. Defaults to false, which shows only the payment or refund type.","example":false},"tax_clause_defaults":{"anyOf":[{"$ref":"#/components/schemas/TaxClauseDefaults"},{"type":"null"}],"description":"Default tax clauses per transaction type. Auto-applied to documents based on transaction type determination. Supports template variables: {entity_name}, {customer_name}, {document_number}, etc."}},"additionalProperties":false,"description":"Business-unit overrides for document-facing settings. Uses the same field names as entity settings while excluding entity-only compliance and fiscalization settings."},"EntitySettingsTranslations":{"type":"object","properties":{"default_invoice_note":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"default_invoice_payment_terms":{"type":"object","properties":{"en-US":{"type":"string","maxLength":500},"de-DE":{"type":"string","maxLength":500},"it-IT":{"type":"string","maxLength":500},"fr-FR":{"type":"string","maxLength":500},"es-ES":{"type":"string","maxLength":500},"sl-SI":{"type":"string","maxLength":500},"pt-PT":{"type":"string","maxLength":500},"nl-NL":{"type":"string","maxLength":500},"pl-PL":{"type":"string","maxLength":500},"hr-HR":{"type":"string","maxLength":500},"sv-SE":{"type":"string","maxLength":500},"fi-FI":{"type":"string","maxLength":500},"et-EE":{"type":"string","maxLength":500},"bg-BG":{"type":"string","maxLength":500},"cs-CZ":{"type":"string","maxLength":500},"sk-SK":{"type":"string","maxLength":500},"nb-NO":{"type":"string","maxLength":500},"is-IS":{"type":"string","maxLength":500}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"default_estimate_note":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"default_estimate_payment_terms":{"type":"object","properties":{"en-US":{"type":"string","maxLength":500},"de-DE":{"type":"string","maxLength":500},"it-IT":{"type":"string","maxLength":500},"fr-FR":{"type":"string","maxLength":500},"es-ES":{"type":"string","maxLength":500},"sl-SI":{"type":"string","maxLength":500},"pt-PT":{"type":"string","maxLength":500},"nl-NL":{"type":"string","maxLength":500},"pl-PL":{"type":"string","maxLength":500},"hr-HR":{"type":"string","maxLength":500},"sv-SE":{"type":"string","maxLength":500},"fi-FI":{"type":"string","maxLength":500},"et-EE":{"type":"string","maxLength":500},"bg-BG":{"type":"string","maxLength":500},"cs-CZ":{"type":"string","maxLength":500},"sk-SK":{"type":"string","maxLength":500},"nb-NO":{"type":"string","maxLength":500},"is-IS":{"type":"string","maxLength":500}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"default_credit_note_note":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"default_credit_note_payment_terms":{"type":"object","properties":{"en-US":{"type":"string","maxLength":500},"de-DE":{"type":"string","maxLength":500},"it-IT":{"type":"string","maxLength":500},"fr-FR":{"type":"string","maxLength":500},"es-ES":{"type":"string","maxLength":500},"sl-SI":{"type":"string","maxLength":500},"pt-PT":{"type":"string","maxLength":500},"nl-NL":{"type":"string","maxLength":500},"pl-PL":{"type":"string","maxLength":500},"hr-HR":{"type":"string","maxLength":500},"sv-SE":{"type":"string","maxLength":500},"fi-FI":{"type":"string","maxLength":500},"et-EE":{"type":"string","maxLength":500},"bg-BG":{"type":"string","maxLength":500},"cs-CZ":{"type":"string","maxLength":500},"sk-SK":{"type":"string","maxLength":500},"nb-NO":{"type":"string","maxLength":500},"is-IS":{"type":"string","maxLength":500}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"default_advance_invoice_note":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"default_delivery_note_note":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"document_footer":{"type":"object","properties":{"en-US":{"type":"string","maxLength":500},"de-DE":{"type":"string","maxLength":500},"it-IT":{"type":"string","maxLength":500},"fr-FR":{"type":"string","maxLength":500},"es-ES":{"type":"string","maxLength":500},"sl-SI":{"type":"string","maxLength":500},"pt-PT":{"type":"string","maxLength":500},"nl-NL":{"type":"string","maxLength":500},"pl-PL":{"type":"string","maxLength":500},"hr-HR":{"type":"string","maxLength":500},"sv-SE":{"type":"string","maxLength":500},"fi-FI":{"type":"string","maxLength":500},"et-EE":{"type":"string","maxLength":500},"bg-BG":{"type":"string","maxLength":500},"cs-CZ":{"type":"string","maxLength":500},"sk-SK":{"type":"string","maxLength":500},"nb-NO":{"type":"string","maxLength":500},"is-IS":{"type":"string","maxLength":500}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"default_document_signature":{"type":"object","properties":{"en-US":{"type":"string","maxLength":1000},"de-DE":{"type":"string","maxLength":1000},"it-IT":{"type":"string","maxLength":1000},"fr-FR":{"type":"string","maxLength":1000},"es-ES":{"type":"string","maxLength":1000},"sl-SI":{"type":"string","maxLength":1000},"pt-PT":{"type":"string","maxLength":1000},"nl-NL":{"type":"string","maxLength":1000},"pl-PL":{"type":"string","maxLength":1000},"hr-HR":{"type":"string","maxLength":1000},"sv-SE":{"type":"string","maxLength":1000},"fi-FI":{"type":"string","maxLength":1000},"et-EE":{"type":"string","maxLength":1000},"bg-BG":{"type":"string","maxLength":1000},"cs-CZ":{"type":"string","maxLength":1000},"sk-SK":{"type":"string","maxLength":1000},"nb-NO":{"type":"string","maxLength":1000},"is-IS":{"type":"string","maxLength":1000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"email_defaults":{"$ref":"#/components/schemas/EmailDefaultTranslations"},"payment_reminders":{"$ref":"#/components/schemas/PaymentReminderTranslations"},"tax_clause_defaults":{"$ref":"#/components/schemas/TaxClauseDefaultTranslations"}},"description":"Translated default document-facing settings keyed by full supported locales. Base scalar settings remain the default-language source of truth."},"EmailDefaultTranslations":{"type":"object","properties":{"invoice_subject":{"type":"object","properties":{"en-US":{"type":"string","maxLength":500},"de-DE":{"type":"string","maxLength":500},"it-IT":{"type":"string","maxLength":500},"fr-FR":{"type":"string","maxLength":500},"es-ES":{"type":"string","maxLength":500},"sl-SI":{"type":"string","maxLength":500},"pt-PT":{"type":"string","maxLength":500},"nl-NL":{"type":"string","maxLength":500},"pl-PL":{"type":"string","maxLength":500},"hr-HR":{"type":"string","maxLength":500},"sv-SE":{"type":"string","maxLength":500},"fi-FI":{"type":"string","maxLength":500},"et-EE":{"type":"string","maxLength":500},"bg-BG":{"type":"string","maxLength":500},"cs-CZ":{"type":"string","maxLength":500},"sk-SK":{"type":"string","maxLength":500},"nb-NO":{"type":"string","maxLength":500},"is-IS":{"type":"string","maxLength":500}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"invoice_body":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"estimate_subject":{"type":"object","properties":{"en-US":{"type":"string","maxLength":500},"de-DE":{"type":"string","maxLength":500},"it-IT":{"type":"string","maxLength":500},"fr-FR":{"type":"string","maxLength":500},"es-ES":{"type":"string","maxLength":500},"sl-SI":{"type":"string","maxLength":500},"pt-PT":{"type":"string","maxLength":500},"nl-NL":{"type":"string","maxLength":500},"pl-PL":{"type":"string","maxLength":500},"hr-HR":{"type":"string","maxLength":500},"sv-SE":{"type":"string","maxLength":500},"fi-FI":{"type":"string","maxLength":500},"et-EE":{"type":"string","maxLength":500},"bg-BG":{"type":"string","maxLength":500},"cs-CZ":{"type":"string","maxLength":500},"sk-SK":{"type":"string","maxLength":500},"nb-NO":{"type":"string","maxLength":500},"is-IS":{"type":"string","maxLength":500}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"estimate_body":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"credit_note_subject":{"type":"object","properties":{"en-US":{"type":"string","maxLength":500},"de-DE":{"type":"string","maxLength":500},"it-IT":{"type":"string","maxLength":500},"fr-FR":{"type":"string","maxLength":500},"es-ES":{"type":"string","maxLength":500},"sl-SI":{"type":"string","maxLength":500},"pt-PT":{"type":"string","maxLength":500},"nl-NL":{"type":"string","maxLength":500},"pl-PL":{"type":"string","maxLength":500},"hr-HR":{"type":"string","maxLength":500},"sv-SE":{"type":"string","maxLength":500},"fi-FI":{"type":"string","maxLength":500},"et-EE":{"type":"string","maxLength":500},"bg-BG":{"type":"string","maxLength":500},"cs-CZ":{"type":"string","maxLength":500},"sk-SK":{"type":"string","maxLength":500},"nb-NO":{"type":"string","maxLength":500},"is-IS":{"type":"string","maxLength":500}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"credit_note_body":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"advance_invoice_subject":{"type":"object","properties":{"en-US":{"type":"string","maxLength":500},"de-DE":{"type":"string","maxLength":500},"it-IT":{"type":"string","maxLength":500},"fr-FR":{"type":"string","maxLength":500},"es-ES":{"type":"string","maxLength":500},"sl-SI":{"type":"string","maxLength":500},"pt-PT":{"type":"string","maxLength":500},"nl-NL":{"type":"string","maxLength":500},"pl-PL":{"type":"string","maxLength":500},"hr-HR":{"type":"string","maxLength":500},"sv-SE":{"type":"string","maxLength":500},"fi-FI":{"type":"string","maxLength":500},"et-EE":{"type":"string","maxLength":500},"bg-BG":{"type":"string","maxLength":500},"cs-CZ":{"type":"string","maxLength":500},"sk-SK":{"type":"string","maxLength":500},"nb-NO":{"type":"string","maxLength":500},"is-IS":{"type":"string","maxLength":500}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"advance_invoice_body":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"delivery_note_subject":{"type":"object","properties":{"en-US":{"type":"string","maxLength":500},"de-DE":{"type":"string","maxLength":500},"it-IT":{"type":"string","maxLength":500},"fr-FR":{"type":"string","maxLength":500},"es-ES":{"type":"string","maxLength":500},"sl-SI":{"type":"string","maxLength":500},"pt-PT":{"type":"string","maxLength":500},"nl-NL":{"type":"string","maxLength":500},"pl-PL":{"type":"string","maxLength":500},"hr-HR":{"type":"string","maxLength":500},"sv-SE":{"type":"string","maxLength":500},"fi-FI":{"type":"string","maxLength":500},"et-EE":{"type":"string","maxLength":500},"bg-BG":{"type":"string","maxLength":500},"cs-CZ":{"type":"string","maxLength":500},"sk-SK":{"type":"string","maxLength":500},"nb-NO":{"type":"string","maxLength":500},"is-IS":{"type":"string","maxLength":500}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"delivery_note_body":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}}},"description":"Translated default email subjects and bodies keyed by full supported locales. Base scalar email defaults remain the default-language source of truth."},"PaymentReminderTranslations":{"type":"object","properties":{"email_subject":{"type":"object","properties":{"en-US":{"type":"string","maxLength":500},"de-DE":{"type":"string","maxLength":500},"it-IT":{"type":"string","maxLength":500},"fr-FR":{"type":"string","maxLength":500},"es-ES":{"type":"string","maxLength":500},"sl-SI":{"type":"string","maxLength":500},"pt-PT":{"type":"string","maxLength":500},"nl-NL":{"type":"string","maxLength":500},"pl-PL":{"type":"string","maxLength":500},"hr-HR":{"type":"string","maxLength":500},"sv-SE":{"type":"string","maxLength":500},"fi-FI":{"type":"string","maxLength":500},"et-EE":{"type":"string","maxLength":500},"bg-BG":{"type":"string","maxLength":500},"cs-CZ":{"type":"string","maxLength":500},"sk-SK":{"type":"string","maxLength":500},"nb-NO":{"type":"string","maxLength":500},"is-IS":{"type":"string","maxLength":500}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"email_body":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"payment_instructions":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}}},"description":"Translated default payment reminder subject, body, and payment instructions keyed by full supported locales."},"TaxClauseDefaultTranslations":{"type":"object","properties":{"domestic":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"intra_eu_b2b":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"intra_eu_b2c":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"3w_b2b":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"3w_b2c":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"export":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}}},"description":"Translated default tax clauses keyed by transaction type. Each transaction-type entry is a localized-content map keyed by full supported locales."},"TaxClauseDefaults":{"type":"object","properties":{"domestic":{"type":["string","null"],"description":"Default tax clause for domestic transactions (same country)","example":null},"intra_eu_b2b":{"type":["string","null"],"description":"Default tax clause for intra-EU B2B transactions (reverse charge applies)","example":"VAT reverse charge - Article 194 of Directive 2006/112/EC. The customer is liable for VAT."},"intra_eu_b2c":{"type":["string","null"],"description":"Default tax clause for intra-EU B2C transactions","example":null},"3w_b2b":{"type":["string","null"],"description":"Default tax clause for third-world B2B transactions (non-EU, business customer)","example":"Export - VAT exempt under Article 146 of Directive 2006/112/EC."},"3w_b2c":{"type":["string","null"],"description":"Default tax clause for third-world B2C transactions (non-EU, end consumer)","example":"Export - VAT exempt under Article 146 of Directive 2006/112/EC."},"export":{"type":["string","null"],"description":"Deprecated: Use 3w_b2b and 3w_b2c instead. Default tax clause for export transactions.","example":"Export - VAT exempt under Article 146 of Directive 2006/112/EC."}}},"DocumentCustomer":{"type":"object","properties":{"name":{"type":["string","null"]},"unit_name":{"type":["string","null"],"deprecated":true,"description":"Deprecated compatibility field. This value is no longer used for business-unit rendering; use `business_unit.name` on the document instead."},"email":{"type":["string","null"],"maxLength":255},"address":{"type":["string","null"]},"address_2":{"type":["string","null"]},"post_code":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]},"country_code":{"type":["string","null"],"maxLength":2},"tax_number":{"type":["string","null"]},"tax_number_2":{"type":["string","null"]},"company_number":{"type":["string","null"]},"phone":{"type":["string","null"]},"peppol_id":{"type":["string","null"]},"peppol_scheme_id":{"type":["string","null"]},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentEInvoicingCustomerData"},{"type":"null"}]},"bank_accounts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/EntityBankAccount"}},"is_end_consumer":{"type":["boolean","null"]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpCustomerData"},{"type":"null"}]},"bank_account":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["iban","us_domestic","uk_domestic","other"],"default":"iban","description":"Account type determines which fields are used","example":"iban"},"name":{"type":["string","null"],"description":"Display name for this account. Falls back to account number if not set","example":"Main Business Account"},"bank_name":{"type":["string","null"],"description":"Bank name","example":"NLB d.d."},"iban":{"type":["string","null"],"description":"IBAN (for type=iban)","example":"SI56012345678901234"},"account_number":{"type":["string","null"],"description":"Account number (for us_domestic, uk_domestic, other)","example":"123456789"},"bic":{"type":["string","null"],"description":"BIC/SWIFT code for international transfers","example":"LJBASI2X"},"routing_number":{"type":["string","null"],"description":"US ABA routing number (for type=us_domestic)","example":"021000021"},"sort_code":{"type":["string","null"],"description":"UK sort code (for type=uk_domestic)","example":"12-34-56"}}}},"description":"Customer recipient snapshot stored on the document. When a document is created with customer_id only, the snapshot is populated from the saved customer. When an explicit customer object is provided, the snapshot is built from that payload and known omitted fields are stored and returned as null instead of being backfilled from the saved customer."},"DocumentTranslations":{"type":"object","properties":{"note":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"payment_terms":{"type":"object","properties":{"en-US":{"type":"string","maxLength":500},"de-DE":{"type":"string","maxLength":500},"it-IT":{"type":"string","maxLength":500},"fr-FR":{"type":"string","maxLength":500},"es-ES":{"type":"string","maxLength":500},"sl-SI":{"type":"string","maxLength":500},"pt-PT":{"type":"string","maxLength":500},"nl-NL":{"type":"string","maxLength":500},"pl-PL":{"type":"string","maxLength":500},"hr-HR":{"type":"string","maxLength":500},"sv-SE":{"type":"string","maxLength":500},"fi-FI":{"type":"string","maxLength":500},"et-EE":{"type":"string","maxLength":500},"bg-BG":{"type":"string","maxLength":500},"cs-CZ":{"type":"string","maxLength":500},"sk-SK":{"type":"string","maxLength":500},"nb-NO":{"type":"string","maxLength":500},"is-IS":{"type":"string","maxLength":500}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"tax_clause":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"footer":{"type":"object","properties":{"en-US":{"type":"string","maxLength":500},"de-DE":{"type":"string","maxLength":500},"it-IT":{"type":"string","maxLength":500},"fr-FR":{"type":"string","maxLength":500},"es-ES":{"type":"string","maxLength":500},"sl-SI":{"type":"string","maxLength":500},"pt-PT":{"type":"string","maxLength":500},"nl-NL":{"type":"string","maxLength":500},"pl-PL":{"type":"string","maxLength":500},"hr-HR":{"type":"string","maxLength":500},"sv-SE":{"type":"string","maxLength":500},"fi-FI":{"type":"string","maxLength":500},"et-EE":{"type":"string","maxLength":500},"bg-BG":{"type":"string","maxLength":500},"cs-CZ":{"type":"string","maxLength":500},"sk-SK":{"type":"string","maxLength":500},"nb-NO":{"type":"string","maxLength":500},"is-IS":{"type":"string","maxLength":500}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"signature":{"type":"object","properties":{"en-US":{"type":"string","maxLength":1000},"de-DE":{"type":"string","maxLength":1000},"it-IT":{"type":"string","maxLength":1000},"fr-FR":{"type":"string","maxLength":1000},"es-ES":{"type":"string","maxLength":1000},"sl-SI":{"type":"string","maxLength":1000},"pt-PT":{"type":"string","maxLength":1000},"nl-NL":{"type":"string","maxLength":1000},"pl-PL":{"type":"string","maxLength":1000},"hr-HR":{"type":"string","maxLength":1000},"sv-SE":{"type":"string","maxLength":1000},"fi-FI":{"type":"string","maxLength":1000},"et-EE":{"type":"string","maxLength":1000},"bg-BG":{"type":"string","maxLength":1000},"cs-CZ":{"type":"string","maxLength":1000},"sk-SK":{"type":"string","maxLength":1000},"nb-NO":{"type":"string","maxLength":1000},"is-IS":{"type":"string","maxLength":1000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}}},"additionalProperties":false,"description":"Translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"CreationSource":{"type":"string","enum":["standard","custom"],"description":"Internal origin of the create request. `standard` means a normal create endpoint calculated the totals. `custom` means the document was created through a `/custom` endpoint."},"DocumentSummaryTax":{"type":"object","properties":{"rate":{"type":["number","null"]},"tax_id":{"type":["string","null"]},"base":{"type":"number"},"amount":{"type":"number"},"base_converted":{"type":["number","null"]},"amount_converted":{"type":["number","null"]},"reverse_charge":{"type":["boolean","null"]}},"required":["rate","base","amount"]},"ExchangeRate":{"type":"object","properties":{"rate":{"type":"number","exclusiveMinimum":0,"description":"Positive exchange rate used for conversion"},"source":{"type":"string","description":"Source of the exchange rate (e.g., 'auto' or 'manual')"},"date":{"type":"string","format":"date-time","description":"Date of the exchange rate"},"quote_currency":{"type":"string","minLength":3,"maxLength":3,"description":"Quote currency (the base currency converted to)"}},"required":["rate","source","date","quote_currency"]},"EslogData":{"type":"object","properties":{"validation_enabled":{"type":["boolean","null"],"description":"Override entity default: true = validate, false = skip, null = use entity setting"},"validation_required":{"type":["boolean","null"],"description":"When true, final document creation/finalization must fail if current e-SLOG validation fails. Draft creation stores validation status without blocking."},"validation_status":{"type":["string","null"],"enum":["valid","invalid","not_validated",null],"description":"Validation status: 'valid', 'invalid', or 'not_validated'"},"validation_errors":{"type":["array","null"],"items":{"type":"string"},"description":"Array of validation error messages (if status is 'invalid')"},"validated_at":{"type":["string","null"],"description":"ISO timestamp when validation was last performed"},"validation_version":{"type":["string","null"],"description":"Validator/generator version used for the stored validation result"},"validation_cache_key":{"type":["string","null"],"description":"Hash of the relevant document/entity data used for the stored validation result"}}},"ViesDocumentData":{"type":"object","properties":{"warning":{"type":["string","null"],"description":"Warning message if VIES validation was unavailable or the VAT number was invalid. Document creation proceeds but this indicates the transaction type may need review."},"skipped":{"type":["boolean","null"],"description":"True when VIES validation was skipped due to entity settings (vies_validate_vat: false) but would normally apply. Used for audit trail."}},"required":["warning","skipped"]},"FursFiscalizationResponse":{"type":"object","properties":{"status":{"type":"string","enum":["pending","success","failed","skipped"]},"fiscalized_at":{"type":"string","format":"date-time"},"error":{"type":"string"},"cancellation_reason":{"type":"string"},"data":{"type":"object","properties":{"zoi":{"type":"string"},"eor":{"type":"string"},"qr_code":{"type":"string"},"business_premise_name":{"type":"string"},"electronic_device_name":{"type":"string"},"invoice_number":{"type":"string"},"iteration":{"type":"integer","default":0},"issue_date_time":{"type":"string"},"payload":{"type":"object","additionalProperties":{},"description":"FURS API request payload"},"issuer_tax_number":{"type":"string"},"operator_tax_number":{"type":"string"},"operator_label":{"type":"string"},"foreign_operator":{"type":"boolean"},"print_count":{"type":"integer","minimum":0},"cancelled":{"type":"boolean"},"cancelled_eor":{"type":"string"},"cancellation_payload":{"type":"object","additionalProperties":{},"description":"FURS API cancellation payload"}},"required":["zoi","business_premise_name","electronic_device_name","invoice_number","payload"]}},"required":["status"],"description":"FURS (Slovenia) fiscalization data. Read-only field, not editable via API. Includes status, premise name, device name, and FURS identifiers (ZOI, EOR, QR code)."},"FinaFiscalizationResponse":{"type":"object","properties":{"status":{"type":"string","enum":["pending","success","failed"]},"fiscalized_at":{"type":"string","format":"date-time"},"error":{"type":"string"},"data":{"type":"object","properties":{"zki":{"type":"string"},"jir":{"type":"string"},"qr_code_url":{"type":"string"},"business_premise_name":{"type":"string"},"electronic_device_name":{"type":"string"},"invoice_number":{"type":"string"},"operator_oib":{"type":"string"},"payment_type":{"type":"string"},"numbering_sequence":{"type":"string"},"issue_date_time":{"type":"string"},"issue_date_time_iso":{"type":"string","format":"date-time"},"payload":{"type":"object","additionalProperties":{},"description":"CIS SOAP request payload"},"subsequent_submit":{"type":"boolean","description":"Server-managed subsequent submission state (FINA NakDost); never accepted as document input."},"issuer_oib":{"type":"string"},"operator_label":{"type":"string"},"print_count":{"type":"integer","minimum":0}},"required":["zki","business_premise_name","electronic_device_name","invoice_number","payload"]}},"required":["status"],"description":"FINA (Croatia) CIS fiscalization data. Read-only field. Includes status, business premise name, electronic device name, and CIS identifiers (ZKI, JIR, QR code URL)."},"GermanEInvoicingData":{"type":"object","properties":{"validation_enabled":{"type":["boolean","null"],"description":"Whether German XRechnung/ZUGFeRD validation was enabled when this document was last validated. This is server-managed document validation state, not buyer/customer routing data."},"validation_required":{"type":["boolean","null"],"description":"Whether this validation result was required for the save/finalization call. When true, final document creation/finalization fails if current German e-invoice validation fails. Draft creation stores validation status without blocking."},"validation_status":{"type":["string","null"],"enum":["valid","invalid","not_validated",null],"description":"Stored German validation status: 'valid', 'invalid', or 'not_validated'. German export downloads require a current valid result; stale or missing results must be refreshed by saving or revalidating the document before export."},"validation_errors":{"type":["array","null"],"items":{"type":"string"},"description":"German XRechnung/ZUGFeRD validation error messages from the last validation run. These messages describe missing or invalid document/entity/customer data."},"validated_at":{"type":["string","null"],"description":"ISO timestamp when validation was last performed."},"validation_version":{"type":["string","null"],"description":"Validator/generator version used for the stored validation result."},"validation_cache_key":{"type":["string","null"],"description":"Hash of the relevant document, entity, and customer data used for the stored validation result. Export code uses this with validation_version to avoid trusting stale validation state."}},"description":"Server-managed validation state for a German e-invoice standard. Stored on invoice and credit-note documents as either xrechnung or zugferd. Buyer reference / Leitweg-ID input belongs under customer.e_invoicing.buyer_reference, not here."},"UjpData":{"type":"object","properties":{"validation_enabled":{"type":["boolean","null"],"description":"Override entity/default behavior: true = validate UJP package requirements, false = skip, null = use default."},"validation_required":{"type":["boolean","null"],"description":"When true, final document creation must fail if current UJP package validation fails."},"validation_status":{"type":["string","null"],"enum":["valid","invalid","not_validated",null],"description":"Validation status for UJP package/envelope requirements."},"validation_errors":{"type":["array","null"],"items":{"type":"string"},"description":"Array of validation error messages when status is invalid."},"validated_at":{"type":["string","null"],"description":"ISO timestamp when UJP validation was last performed."},"validation_version":{"type":["string","null"],"description":"Validator/generator version used for the stored UJP validation result."},"validation_cache_key":{"type":["string","null"],"description":"Hash of the relevant document/entity data used for the stored UJP validation result."}},"description":"UJP package validation data for Slovenian invoice/credit-note exports. Web may expose UJP download as a secondary e-SLOG dropdown action when current UJP validation is valid."},"InvoiceItem":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"type":{"type":["string","null"],"enum":["separator",null],"description":"Item type. null = regular line item, 'separator' = visual section header."},"name":{"type":"string","maxLength":500},"description":{"type":["string","null"]},"classification":{"type":["string","null"],"enum":["product","service","advance",null],"description":"Item classification used for Portugal SAF-T product typing.","example":"service"},"price":{"type":["number","null"],"description":"Per-unit net price before tax in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. Always stores net price. Null for separator items.","example":100},"gross_price":{"type":["number","null"],"description":"Per-unit gross price including tax in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents.\nOnly present if user originally sent gross price.\nUse gross pricing to keep invoice totals stable when VIES reverse charge is applied.","example":122},"quantity":{"type":["number","null"],"description":"Item quantity. Null for separator items.","example":1},"unit":{"type":["string","null"],"description":"Display unit for this line item. E-invoicing XML unit output may be overridden by `e_invoicing.unit_code`.","example":"hours"},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemEInvoicingData"},{"type":"null"}],"description":"Line-level e-invoicing options for XML output."},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentItemTax"},"description":"Applied taxes (provide rate to create new tax, or tax_id to use existing tax)"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/LineDiscount"},"maxItems":5,"description":"Line discounts (max 5) in request order. In `b2b_standard`, percentage discounts are calculated from the original line subtotal and fixed amounts are summed before tax. In `b2c_gross_discount`, discounts are applied sequentially to the running gross subtotal.","example":[{"value":10,"type":"percent"}]},"total":{"type":["number","null"],"description":"Line total before tax in the document currency's major unit. Null for separator items.","example":100},"total_with_tax":{"type":["number","null"],"description":"Line total after tax in the document currency's major unit. Null for separator items.","example":122},"total_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"total_with_tax_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"invoice_id":{"type":["string","null"],"maxLength":36},"advance_invoice_id":{"type":["string","null"],"maxLength":36},"delivery_note_id":{"type":["string","null"],"maxLength":36},"expense_id":{"type":["string","null"],"maxLength":36},"item_id":{"type":["string","null"],"maxLength":36},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"revenue_recognition":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemRevenueRecognition"},{"type":"null"}],"description":"Optional line-level revenue recognition override."},"translations":{"$ref":"#/components/schemas/DocumentItemTranslations"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"financial_category_id":{"type":["string","null"],"description":"Reporting financial category assigned to this document line.","example":"fcat_abc123"}},"required":["id","name","description","taxes","discounts","translations","created_at","updated_at"]},"DocumentItemEInvoicingData":{"type":"object","properties":{"unit_code":{"type":["string","null"],"minLength":1,"maxLength":8,"description":"Optional XML unit-code override for e-SLOG, Peppol, XRechnung, and ZUGFeRD output. Use a supported UN/ECE Rec 20 / Rec 21 code such as C62, HUR, MGM, MLT, or SET.","example":"C62"}},"additionalProperties":false,"description":"Line-level e-invoicing options. `unit_code` overrides only XML unit output; the line `unit` field remains the display unit."},"DocumentItemTax":{"type":"object","properties":{"rate":{"type":["number","null"]},"tax_id":{"type":["string","null"]},"classification":{"type":["string","null"]},"reverse_charge":{"type":["boolean","null"]},"amount":{"type":["number","null"]},"is_deductible":{"type":["boolean","null"],"description":"AP compatibility flag derived from deductible_percentage when supplied. Without a percentage, true resolves to 100 and false resolves to 0."},"deductible_percentage":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Percentage of input tax that is deductible for AP bookkeeping, from 0 through 100."},"pt_exemption_code":{"type":["string","null"]},"pt_exemption_reason":{"type":["string","null"]}},"additionalProperties":false,"description":"Document Item Tax"},"LineDiscount":{"type":"object","properties":{"value":{"type":"number","minimum":0,"description":"Discount value","example":10},"type":{"type":"string","enum":["percent","amount"],"default":"percent","description":"Discount type: 'percent' (default) or 'amount'","example":"percent"}},"required":["value"],"additionalProperties":false},"DocumentItemRevenueRecognition":{"type":"object","properties":{"method":{"type":["string","null"],"enum":["immediate","service_period_daily",null],"description":"Line-level revenue recognition override. immediate recognizes on the document date; service_period_daily spreads over date_from/date_to.","example":"service_period_daily"},"date_from":{"type":["string","null"],"description":"Line-level service period start date in YYYY-MM-DD format.","example":"2026-05-15"},"date_to":{"type":["string","null"],"description":"Line-level service period end date in YYYY-MM-DD format.","example":"2027-05-14"}},"additionalProperties":false},"DocumentItemTranslations":{"type":"object","properties":{"name":{"type":"object","properties":{"en-US":{"type":"string","maxLength":500},"de-DE":{"type":"string","maxLength":500},"it-IT":{"type":"string","maxLength":500},"fr-FR":{"type":"string","maxLength":500},"es-ES":{"type":"string","maxLength":500},"sl-SI":{"type":"string","maxLength":500},"pt-PT":{"type":"string","maxLength":500},"nl-NL":{"type":"string","maxLength":500},"pl-PL":{"type":"string","maxLength":500},"hr-HR":{"type":"string","maxLength":500},"sv-SE":{"type":"string","maxLength":500},"fi-FI":{"type":"string","maxLength":500},"et-EE":{"type":"string","maxLength":500},"bg-BG":{"type":"string","maxLength":500},"cs-CZ":{"type":"string","maxLength":500},"sk-SK":{"type":"string","maxLength":500},"nb-NO":{"type":"string","maxLength":500},"is-IS":{"type":"string","maxLength":500}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}},"description":{"type":"object","properties":{"en-US":{"type":"string","maxLength":2000},"de-DE":{"type":"string","maxLength":2000},"it-IT":{"type":"string","maxLength":2000},"fr-FR":{"type":"string","maxLength":2000},"es-ES":{"type":"string","maxLength":2000},"sl-SI":{"type":"string","maxLength":2000},"pt-PT":{"type":"string","maxLength":2000},"nl-NL":{"type":"string","maxLength":2000},"pl-PL":{"type":"string","maxLength":2000},"hr-HR":{"type":"string","maxLength":2000},"sv-SE":{"type":"string","maxLength":2000},"fi-FI":{"type":"string","maxLength":2000},"et-EE":{"type":"string","maxLength":2000},"bg-BG":{"type":"string","maxLength":2000},"cs-CZ":{"type":"string","maxLength":2000},"sk-SK":{"type":"string","maxLength":2000},"nb-NO":{"type":"string","maxLength":2000},"is-IS":{"type":"string","maxLength":2000}},"description":"Translated user-authored document content keyed by full supported locales such as `de-DE`. Values may be empty strings to intentionally blank content for a locale.","example":{"de-DE":"Beispieltext"}}},"additionalProperties":false,"description":"Translated user-authored line-item content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"name":{"de-DE":"Beratungsleistungen"},"description":{"de-DE":"Retainer fuer Maerz"}}},"DocumentRelation":{"type":"object","properties":{"id":{"type":"string"},"source_type":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice","delivery_note"],"description":"Type of document"},"source_id":{"type":"string"},"target_type":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice","delivery_note"],"description":"Type of document"},"target_id":{"type":"string"},"relation_type":{"type":"string"},"entity_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"linked_document_voided_at":{"type":["string","null"],"format":"date-time"},"related_document":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice","delivery_note"],"description":"Type of document"},"number":{"type":"string"},"date":{"type":"string"},"total_with_tax":{"type":"number"},"currency_code":{"type":"string"},"is_draft":{"type":"boolean"},"voided_at":{"type":["string","null"]},"paid_in_full":{"type":["boolean","null"]},"title_type":{"type":["string","null"],"enum":["estimate","proforma_invoice",null]},"hide_prices":{"type":["boolean","null"]}},"required":["id","type","number","date","total_with_tax","currency_code","is_draft","voided_at","paid_in_full","title_type","hide_prices"]}},"required":["id","source_type","source_id","target_type","target_id","relation_type","entity_id","created_at"]},"Error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code (e.g., validation_error, unauthorized, not_found)"},"message":{"type":"string","description":"Human-readable error message describing what went wrong"}},"required":["code","message"],"description":"Standard error response format used across all API endpoints. Includes a machine-readable error code and human-readable message."},"ValidationError":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"cause":{"type":"object","additionalProperties":{},"description":"Detailed validation error information from Zod. Contains field names as keys with _errors arrays for each validation failure. Supports nested fields."}}}],"description":"Standard error response format used across all API endpoints. Includes a machine-readable error code and human-readable message."},"CreateInvoice":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtDocumentInput"},{"type":"null"}]},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the invoice. At least one item is required."},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this invoice to other documents. Accepts estimate IDs (est_xxx) for converted estimates or credit note IDs (cre_xxx). Creates document relations automatically.","example":["est_abc123"]},"payments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentPayment"},"description":"Optional payments to record with the invoice. If amounts are not provided, the invoice total is split equally among all payments. Automatically updates invoice payment status."},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"furs":{"anyOf":[{"$ref":"#/components/schemas/CreateFursDocumentData"},{"type":"null"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/CreateFinaInvoiceData"},{"type":"null"}]},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentEInvoicingSendInput"},{"type":"null"}]},"xrechnung":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"zugferd":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpInput"},{"type":"null"}]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"force_linked_documents":{"type":["boolean","null"],"description":"Force linking documents even if an advance invoice is already applied to another invoice. Defaults to false."}},"required":["items"],"additionalProperties":false},"CreateDocumentBusinessUnit":{"allOf":[{"$ref":"#/components/schemas/BusinessUnitSnapshot"},{"type":"object","properties":{"settings":{"anyOf":[{"$ref":"#/components/schemas/BusinessUnitSettings"},{"type":"null"}]}}}],"description":"Business-unit snapshot to store on the document. If provided, this explicit snapshot is stored instead of backfilling omitted fields from the saved business unit. Omitted nullable snapshot fields are stored and returned as null."},"CreateDocumentCustomer":{"allOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"type":"object","properties":{"save_customer":{"type":["boolean","null"],"description":"Whether to save (create new or update existing) the customer data.\nDefaults to `true` (best-effort).\nWhen `true` with `customer_id`, updates the existing customer.\nWhen `true` without `customer_id`, checks for duplicate customers using customer identifiers (tax/company number, country-aware when available) and reuses the existing customer if found, otherwise creates a new customer.\nWhen `false`, customer data is stored inline on the document only.\nWhen omitted, behaves like `true` but won't fail the request if persistence fails."}}}],"description":"Customer recipient of the document.\nBoth `customer` and `customer_id` are optional - documents can be created without customer information.\nIf only `customer_id` is provided, the document customer snapshot is populated from the saved customer.\nIf `customer` is provided, the document customer snapshot is built from the explicit payload; saved customer fields are not backfilled into omitted snapshot fields.\nIf both `customer_id` and `customer` are provided with `save_customer=true`, the existing customer will be updated from explicit customer fields only. Omitted fields remain unchanged on the saved customer, and explicit null clears nullable saved customer fields.\nIf only `customer` is provided with `save_customer=true` (or by default), the system checks for duplicate customers using customer identifiers and reuses the existing customer if found, otherwise creates a new customer."},"PtDocumentInput":{"type":"object","properties":{"series_id":{"type":["string","null"],"description":"ATCUD series ID to use for PT numbering. Required for PT manual documents.","example":"atcud_123"},"manual":{"type":["boolean","null"],"description":"Marks this PT document as manually issued/offline.","example":false},"manual_sequential_number":{"type":["integer","null"],"minimum":1,"description":"Manual PT sequence number shown on the offline/original document.","example":123},"manual_series_code":{"type":["string","null"],"minLength":1,"maxLength":35,"description":"Offline/manual PT series code shown on the original document.","example":"ABC"},"operator_first_name":{"type":["string","null"],"minLength":1,"description":"PT operator first name snapshot for PT compliance.","example":"Antonio"},"operator_last_name":{"type":["string","null"],"minLength":1,"description":"PT operator last name snapshot for PT compliance.","example":"Silva"},"operator_tax_number":{"type":["string","null"],"minLength":1,"description":"PT operator tax number snapshot for PT compliance.","example":"123456789"},"account_first_name":{"type":["string","null"],"minLength":1,"description":"Deprecated alias for PT operator first name snapshot.","example":"Antonio"},"account_last_name":{"type":["string","null"],"minLength":1,"description":"Deprecated alias for PT operator last name snapshot.","example":"Silva"},"account_tax_number":{"type":["string","null"],"minLength":1,"description":"Deprecated alias for PT operator tax number snapshot.","example":"123456789"}},"additionalProperties":false},"CreateDocumentItem":{"type":"object","properties":{"type":{"type":["string","null"],"enum":["separator",null],"description":"Item type. Omit or null for regular line item, 'separator' for a visual section header.\nSeparator items only use name and description — all financial fields are ignored."},"name":{"type":["string","null"],"minLength":1,"description":"Item name. Required unless `item_id` is provided.\nFor separator items, this is the section title (always required)."},"description":{"type":["string","null"],"maxLength":2000},"classification":{"type":["string","null"],"enum":["product","service","advance",null],"description":"Item classification used for Portugal SAF-T product typing.","example":"service"},"price":{"type":["number","null"],"description":"Net price per unit before tax in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents.\nProvide either `price` OR `gross_price`, not both.\nOptional if `item_id` is provided. Ignored for separator items.","example":100},"gross_price":{"type":["number","null"],"description":"Gross price per unit including tax in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents.\nIf provided, net price is calculated.\nProvide either `price` OR `gross_price`, not both.\nOptional if `item_id` is provided. Ignored for separator items.","example":122},"quantity":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327,"description":"Item quantity. Required for regular items. Ignored for separator items.","example":1},"unit":{"type":["string","null"],"description":"Display unit for this line item. E-invoicing XML unit output may be overridden by `e_invoicing.unit_code`.","example":"hours"},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemEInvoicingData"},{"type":"null"}],"description":"Line-level e-invoicing options for XML output."},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentItemTax"},"description":"Applied taxes (provide rate to create new tax, or tax_id to use existing tax)"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/LineDiscount"},"maxItems":5,"description":"Line discounts (max 5) in request order. In `b2b_standard`, percentage discounts are calculated from the original line subtotal and fixed amounts are summed before tax. In `b2c_gross_discount`, discounts are applied sequentially to the running gross subtotal.","example":[{"value":10,"type":"percent"}]},"item_id":{"type":["string","null"],"description":"ID of a catalog item to prefill from.\nWhen provided, the item's name, description, price, and taxes are used as defaults.\nAny field you provide will override the catalog item's value.\nNot applicable for separator items.","example":"item_abc123"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"revenue_recognition":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemRevenueRecognition"},{"type":"null"}],"description":"Optional line-level revenue recognition override. Omit to use the document service period and entity setting."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentItemTranslations"},{"description":"Translated user-authored line-item content keyed by full supported locales. Base item fields remain the default-language source of truth."}]},{"type":"null"}],"description":"Optional or null translated user-authored line-item content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"name":{"de-DE":"Beratungsleistungen"},"description":{"de-DE":"Retainer fuer Maerz"}}},"financial_category_id":{"type":["string","null"],"description":"Reporting financial category to assign to this line item.","example":"fcat_abc123"},"save_item":{"type":["boolean","null"],"description":"Whether to save this item to the catalog.\nWhen true without item_id, matches by exact name and reuses existing, or creates a new catalog item.\nDefaults to true (best-effort). When omitted, behaves like true but won't fail the request if persistence fails."}},"additionalProperties":false},"CreateDocumentPayment":{"type":"object","properties":{"amount":{"type":["number","null"],"exclusiveMinimum":0,"description":"Payment amount in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. If omitted, the document total (`total_with_tax`) is used."},"type":{"type":"string","enum":["cash","bank_transfer","card","check","paypal","coupon","other","credit_note","advance"],"description":"Payment type/method"},"date":{"type":["string","null"],"description":"Payment date in YYYY-MM-DD format. Defaults to today.","example":"2024-01-15"},"tag":{"type":["string","null"]},"reference":{"type":["string","null"]},"note":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"required":["type"],"additionalProperties":false},"CreateDocumentCategoryAssignment":{"type":"object","properties":{"item_index":{"type":["integer","null"],"minimum":0,"description":"Zero-based index of the target line item in the request `items` array. Omit or null on a single entry to apply the assignment to all non-separator items.","example":0},"financial_category_id":{"type":["string","null"],"description":"Reporting financial category to assign to the targeted document line. Use null to explicitly leave the targeted item or full document uncategorized.","example":"fcat_abc123"}},"additionalProperties":false},"CreateFursDocumentData":{"type":"object","properties":{"business_premise_name":{"type":["string","null"],"minLength":1,"description":"FURS business premise name (e.g., 'P1', 'STORE1'). Required unless skip=true.","example":"P1"},"electronic_device_name":{"type":["string","null"],"minLength":1,"description":"FURS electronic device name (e.g., 'E1', 'POS1'). Required unless skip=true.","example":"E1"},"operator_tax_number":{"type":["string","null"],"description":"Operator tax number. If not provided and using user authentication, defaults to user's FURS settings.","example":"12345678"},"operator_label":{"type":["string","null"],"description":"Operator label/name. If not provided and using user authentication, defaults to user's FURS settings.","example":"John Doe"},"skip":{"type":["boolean","null"],"description":"Skip FURS fiscalization. Only allowed for bank transfer payments or unpaid invoices. Cash/card/check payments always require fiscalization per Slovenian law.","example":false}},"additionalProperties":false},"CreateFinaInvoiceData":{"type":"object","properties":{"business_premise_name":{"type":["string","null"],"minLength":1,"maxLength":20,"pattern":"^[0-9a-zA-Z]{1,20}$","description":"CIS business premise name (OznPosPr, alphanumeric, 1-20 chars). Required when CIS is enabled.","example":"PP1"},"electronic_device_name":{"type":["string","null"],"minLength":1,"maxLength":20,"pattern":"^\\d{1,20}$","description":"CIS electronic device name (OznNapUr, digits only, 1-20 chars). Required when CIS is enabled.","example":"1"},"operator_oib":{"type":["string","null"],"minLength":11,"maxLength":11,"description":"Operator OIB (11 digits). If not provided and using user authentication, defaults to the user's FINA settings. Otherwise falls back to entity settings.","example":"12345678901"},"operator_label":{"type":["string","null"],"description":"Operator label/name. If not provided and using user authentication, defaults to the user's FINA settings. Otherwise falls back to entity settings.","example":"Ivan Horvat"},"payment_type":{"type":["string","null"],"enum":["cash","card","online","bank_transfer","paypal","crypto","coupon","other",null],"description":"Expected payment method for CIS (NacinPlac field). Optional when document payments are provided because the API derives it from the document payments; when multiple payments are present, FINA uses 'other'.","example":"cash"}},"additionalProperties":false},"EslogInput":{"type":"object","properties":{"validation_enabled":{"type":["boolean","null"],"description":"Enable e-SLOG validation for this document. true = validate, false = skip, null/undefined = use entity default"},"validation_required":{"type":["boolean","null"],"description":"Require e-SLOG validation to pass before creating a final document or finalizing a draft. Draft creation stores validation status without blocking."}}},"DocumentEInvoicingSendInput":{"type":"object","properties":{"send_enabled":{"type":["boolean","null"],"description":"Whether this document is eligible for automatic Peppol sending when entity e-invoicing auto-send is enabled. Defaults to true when omitted.","example":true}},"additionalProperties":false,"description":"Per-document Peppol sending controls for invoices and credit notes."},"GermanEInvoicingInput":{"type":"object","properties":{"validation_enabled":{"type":["boolean","null"],"description":"Override whether this document should be validated for German XRechnung/ZUGFeRD on this request. Entity-level XRechnung/ZUGFeRD settings enable soft validation by default; false can suppress that optional validation for this request unless validation_required is true."},"validation_required":{"type":["boolean","null"],"description":"Request strict German validation for this document. Final document creation/finalization fails if current validation is invalid; draft creation stores validation status without blocking. Export/download still requires current valid validation for the requested standard."}},"description":"Optional per-document German validation controls accepted on invoice and credit-note create/preview payloads as xrechnung or zugferd. This input does not contain XRechnung buyer reference or Leitweg-ID; send that value as customer.e_invoicing.buyer_reference."},"UjpInput":{"type":"object","properties":{"validation_enabled":{"type":["boolean","null"],"description":"Enable UJP package validation for this document. true = validate, false = skip, null/undefined = use default."},"validation_required":{"type":["boolean","null"],"description":"Require UJP validation to pass before final document creation. Draft creation records validation status but does not block."}}},"CustomCreateInvoice":{"type":"object","properties":{"is_draft":{"type":["boolean","null"]},"date":{"type":["string","null"]},"issuer":{"anyOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"type":"null"}]},"business_unit_id":{"type":["string","null"]},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"]},"payment_terms":{"type":["string","null"]},"tax_clause":{"type":["string","null"]},"footer":{"type":["string","null"]},"signature":{"type":["string","null"]},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"]},"date_due":{"type":["string","null"]},"pt":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"date_service":{"type":["string","null"]},"date_service_to":{"type":["string","null"]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"items":{"type":"array","items":{"$ref":"#/components/schemas/CustomDocumentItem"},"minItems":1,"description":"Line items with pre-calculated totals. At least one item is required."},"total":{"type":"number","description":"Pre-calculated document total (before tax).","example":1000},"total_with_tax":{"type":"number","description":"Pre-calculated document total (after tax).","example":1220},"total_discount":{"type":["number","null"],"description":"Pre-calculated total net discount amount. Defaults to 0 if not provided."},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"},"description":"Pre-calculated tax summary. If not provided, defaults to empty array."},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this invoice to other documents.","example":["est_abc123"]},"payments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentPayment"},"description":"Optional payments to record with the invoice. If amounts are not provided, the invoice total is split equally among all payments. Automatically updates invoice payment status."},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"furs":{"anyOf":[{"$ref":"#/components/schemas/CreateFursDocumentData"},{"type":"null"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/CreateFinaInvoiceData"},{"type":"null"}]},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentEInvoicingSendInput"},{"type":"null"}]},"xrechnung":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"zugferd":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpInput"},{"type":"null"}]},"force_linked_documents":{"type":["boolean","null"],"description":"Force linking documents even if an advance invoice is already applied to another invoice. Defaults to false."}},"required":["items","total","total_with_tax"],"additionalProperties":false},"CustomDocumentItem":{"type":"object","properties":{"type":{"type":["string","null"],"enum":["separator",null],"description":"Item type. Omit or null for regular line item, 'separator' for a visual section header.\nSeparator items only use name and description — all financial fields are ignored."},"name":{"type":["string","null"],"minLength":1,"description":"Item name. Required unless `item_id` is provided.\nFor separator items, this is the section title (always required)."},"description":{"type":["string","null"],"maxLength":2000},"classification":{"type":["string","null"],"enum":["product","service","advance",null],"description":"Item classification used for Portugal SAF-T product typing.","example":"service"},"price":{"type":["number","null"],"description":"Net price per unit before tax in the document currency's major unit. Optional for custom documents. Ignored for separator items.","example":100},"gross_price":{"type":["number","null"],"description":"Gross price per unit including tax in the document currency's major unit. Optional for custom documents. Ignored for separator items.","example":122},"quantity":{"type":["number","null"],"description":"Item quantity. Null for separator items.","example":1},"unit":{"type":["string","null"],"description":"Display unit for this line item. E-invoicing XML unit output may be overridden by `e_invoicing.unit_code`.","example":"hours"},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemEInvoicingData"},{"type":"null"}],"description":"Line-level e-invoicing options for XML output."},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentItemTax"},"description":"Applied taxes (provide rate to create new tax, or tax_id to use existing tax)"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/LineDiscount"},"maxItems":5,"description":"Line discounts (max 5) in request order. In `b2b_standard`, percentage discounts are calculated from the original line subtotal and fixed amounts are summed before tax. In `b2c_gross_discount`, discounts are applied sequentially to the running gross subtotal.","example":[{"value":10,"type":"percent"}]},"total":{"type":["number","null"],"description":"Pre-calculated total for this line item before tax in the document currency's major unit. Ignored for separator items.","example":1000},"total_with_tax":{"type":["number","null"],"description":"Pre-calculated total for this line item after tax in the document currency's major unit. Ignored for separator items.","example":1220},"item_id":{"type":["string","null"],"description":"ID of a catalog item to prefill from.\nWhen provided, the item's name, description, price, and taxes are used as defaults.\nAny field you provide will override the catalog item's value.\nNot applicable for separator items.","example":"item_abc123"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"revenue_recognition":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemRevenueRecognition"},{"type":"null"}],"description":"Optional line-level revenue recognition override. Omit to use the document service period and entity setting."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentItemTranslations"},{"description":"Translated user-authored line-item content keyed by full supported locales. Base item fields remain the default-language source of truth."}]},{"type":"null"}],"description":"Optional or null translated user-authored line-item content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"name":{"de-DE":"Beratungsleistungen"},"description":{"de-DE":"Retainer fuer Maerz"}}},"financial_category_id":{"type":["string","null"],"description":"Reporting financial category to assign to this line item.","example":"fcat_abc123"},"save_item":{"type":["boolean","null"],"description":"Whether to save this item to the catalog.\nWhen true without item_id, matches by exact name and reuses existing, or creates a new catalog item.\nDefaults to true (best-effort). When omitted, behaves like true but won't fail the request if persistence fails."}},"additionalProperties":false},"InvoiceList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"number","description":"Total number of items available in the collection"},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for fetching the next page. It encodes the resolved sort tuple for the current result set, so reuse it only with the same effective ordering. Null if no more results are available."},"prev_cursor":{"type":["string","null"],"description":"Opaque cursor for fetching the previous page. It encodes the resolved sort tuple for the current result set, so reuse it only with the same effective ordering. Null if at the first page."},"has_more":{"type":"boolean","description":"Indicates whether more results are available after the current page"}},"required":["total","next_cursor","prev_cursor","has_more"],"description":"Pagination metadata including cursors and result counts"},"UpdateInvoice":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date (YYYY-MM-DD or ISO datetime format).","example":"2024-01-15"},"issuer":{"allOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"description":"Issuer information snapshot."}]},"business_unit_id":{"type":["string","null"],"description":"Selected business unit. Set to null to revert the document to the main entity. When provided without `business_unit`, the document business-unit snapshot is populated from the saved business unit."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Set to null to remove customer reference."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the document. If provided, replaces ALL existing items. Standard documents recalculate totals. Custom documents created with pre-calculated totals preserve existing totals when item financial inputs are unchanged."},"note":{"type":["string","null"],"description":"Document note/memo. Set to null to clear."},"payment_terms":{"type":["string","null"],"description":"Payment terms text. Set to null to clear."},"tax_clause":{"type":["string","null"],"description":"Tax clause text. Set to null to clear."},"footer":{"type":["string","null"],"description":"Footer text. Set to null to clear."},"signature":{"type":["string","null"],"description":"Signature text (e.g. 'John Smith, CEO'). Set to null to clear."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Translated user-authored document content. Set to null to clear all translations.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"currency_code":{"type":"string","description":"Currency code (ISO 4217, 3 characters). Changing currency triggers exchange rate recalculation.","example":"EUR"},"reference":{"type":["string","null"],"maxLength":100,"description":"Custom reference (e.g., purchase order number, payment reference). When set, overrides the auto-generated UPN payment reference for Slovenian invoices. Set to null to clear."},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Custom metadata object. Set to null to clear."},"change_reason":{"type":"string","maxLength":500,"description":"Reason for the change. Stored in version history for audit trail.","example":"Corrected customer address"},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Payment due date (YYYY-MM-DD or ISO datetime format). Set to null to clear.","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service/work date or start of service period. Set to null to clear.","example":"2024-01-01"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"End of service period (if different from date_service). Set to null to clear.","example":"2024-01-31"},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this invoice to other documents. Replaces existing links. Accepts estimate IDs (est_xxx) or credit note IDs (cre_xxx).","example":["est_abc123"]},"force_linked_documents":{"type":"boolean","description":"Force linking documents even if a target document is already linked to another invoice. Defaults to false."},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]},"xrechnung":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"zugferd":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpInput"},{"type":"null"}]}},"additionalProperties":false},"DocumentVersionList":{"type":"object","properties":{"versions":{"type":"array","items":{"$ref":"#/components/schemas/DocumentVersion"},"description":"List of versions"},"count":{"type":"integer","description":"Total number of versions"}},"required":["versions","count"]},"DocumentVersion":{"type":"object","properties":{"id":{"type":"string","description":"Version record ID"},"document_type":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice"],"description":"Type of document"},"document_id":{"type":"string","description":"Document ID"},"version":{"type":"integer","minimum":1,"description":"Version number"},"snapshot":{"type":"object","additionalProperties":{},"description":"Full document snapshot at this version"},"changed_fields":{"type":"array","items":{"type":"string"},"description":"Fields that were changed in this update"},"user":{"anyOf":[{"$ref":"#/components/schemas/VersionUser"},{"type":"null"}],"description":"User who made the change"},"reason":{"type":["string","null"],"description":"Reason for the change"},"created_at":{"type":"string","format":"date-time","description":"When this version was created"}},"required":["id","document_type","document_id","version","snapshot","changed_fields","user","reason","created_at"]},"VersionUser":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":"string"}},"required":["id","name","email"]},"PartialInvoicePreview":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtDocumentInput"},{"type":"null"}]},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["separator"]},"name":{"type":"string"},"quantity":{"type":"number"},"price":{"type":"number"},"gross_price":{"type":"number"},"description":{"type":"string"},"unit":{"type":"string"},"discounts":{"type":"array","items":{"type":"object","properties":{"value":{"type":"number"},"type":{"type":"string","enum":["percent","amount"]}},"required":["value"]}},"taxes":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"},"tax_id":{"type":"string"}}}},"total":{"type":"number"},"total_with_tax":{"type":"number"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"minItems":1},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this invoice to other documents. Accepts estimate IDs (est_xxx) for converted estimates or credit note IDs (cre_xxx). Creates document relations automatically.","example":["est_abc123"]},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/CreateFinaInvoiceData"},{"type":"null"}]},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentEInvoicingSendInput"},{"type":"null"}]},"xrechnung":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"zugferd":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpInput"},{"type":"null"}]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"force_linked_documents":{"type":["boolean","null"],"description":"Force linking documents even if an advance invoice is already applied to another invoice. Defaults to false."},"id":{"type":"string"},"furs":{"anyOf":[{"$ref":"#/components/schemas/CreateFursDocumentData"},{"type":"null"}]},"creation_source":{"type":"string","enum":["custom"]},"total":{"type":"number"},"total_with_tax":{"type":"number"},"total_discount":{"type":["number","null"]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"}}},"required":["items"],"additionalProperties":false},"CompleteInvoicePreview":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtDocumentInput"},{"type":"null"}]},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the invoice. At least one item is required."},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this invoice to other documents. Accepts estimate IDs (est_xxx) for converted estimates or credit note IDs (cre_xxx). Creates document relations automatically.","example":["est_abc123"]},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/CreateFinaInvoiceData"},{"type":"null"}]},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentEInvoicingSendInput"},{"type":"null"}]},"xrechnung":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"zugferd":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpInput"},{"type":"null"}]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"force_linked_documents":{"type":["boolean","null"],"description":"Force linking documents even if an advance invoice is already applied to another invoice. Defaults to false."},"id":{"type":"string"},"furs":{"anyOf":[{"$ref":"#/components/schemas/CreateFursDocumentData"},{"type":"null"}]},"creation_source":{"type":"string","enum":["custom"]},"total":{"type":"number"},"total_with_tax":{"type":"number"},"total_discount":{"type":["number","null"]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"}}},"required":["items"],"additionalProperties":false},"Estimate":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"number":{"type":"string","maxLength":100},"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","format":"date-time","description":"Date the estimate was created (ISO 8601 datetime at midnight UTC)"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/BusinessUnitSnapshot"},{"type":"null"}],"description":"Frozen business-unit snapshot used for stable rendering and historical accuracy."},"customer_id":{"type":["string","null"],"maxLength":36},"customer":{"anyOf":[{"$ref":"#/components/schemas/DocumentCustomer"},{"type":"null"}],"description":"Customer information snapshot stored on the document. Null means no customer. When present, known customer fields are returned with null for omitted values."},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"$ref":"#/components/schemas/DocumentTranslations"},"total":{"type":"number","description":"Document total before tax in the currency's major unit. For EUR, `29.90` means €29.90, not 2,990 cents."},"total_with_tax":{"type":"number","description":"Document total after tax in the currency's major unit. For EUR, `29.90` means €29.90, not 2,990 cents."},"total_discount":{"type":"number","description":"Document discount total in the currency's major unit, stored as a net-equivalent amount for compatibility. In `b2b_standard`, this is the net value of line-item discounts applied before tax. In `b2c_gross_discount`, gross discounts are converted back to their net-equivalent value here. 0 when no discounts applied."},"creation_source":{"$ref":"#/components/schemas/CreationSource"},"calculation_mode":{"type":"string","enum":["b2b_standard","b2c_gross_discount"],"description":"Resolved calculation mode used for this document. Stored on the document so recalculation and rendering remain stable even if entity defaults change later.","example":"b2b_standard"},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"},"description":"Applied taxes summary"},"currency_code":{"type":"string","maxLength":3},"entity_id":{"type":"string","maxLength":36},"date_year":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"shareable_id":{"type":["string","null"],"maxLength":100},"voided_at":{"type":["string","null"],"format":"date-time"},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export",null],"description":"Transaction type for VAT purposes (domestic, intra_eu_b2b, intra_eu_b2c, export). Always determined based on issuer/customer countries."},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"exchange_rate":{"anyOf":[{"$ref":"#/components/schemas/ExchangeRate"},{"type":"null"}],"description":"Currency exchange rate information if conversion was applied"},"total_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"total_with_tax_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"rounding_correction":{"type":["number","null"],"description":"Rounding correction in the currency's major unit, applied to reconcile differences between calculated total_with_tax and expected_total_with_tax. Only present when expected_total_with_tax was provided during creation."},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogData"},{"type":"null"}],"description":"e-SLOG 2.0 validation data for Slovenian electronic invoices. Only applicable when entity.country_code = 'SI' and eslog validation is enabled."},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"vies":{"anyOf":[{"$ref":"#/components/schemas/ViesDocumentData"},{"type":"null"},{"type":"null"}],"description":"VIES validation info including any warnings and skipped indicator for audit trail"},"deleted_at":{"type":["string","null"],"format":"date-time","description":"Timestamp when the document was soft-deleted. Null if not deleted."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"pt":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"date_valid_till":{"type":["string","null"],"format":"date-time","description":"Date until which the estimate is valid (ISO 8601 datetime at midnight UTC)"},"title_type":{"type":["string","null"],"enum":["estimate","proforma_invoice",null],"description":"Display name variant for the document. 'estimate' renders as 'Estimate' (Ponudba/Ponuda), 'proforma_invoice' renders as 'Proforma invoice' (Predračun).","example":"estimate"},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"$ref":"#/components/schemas/EstimateItem"}},"document_relations":{"type":"array","items":{"$ref":"#/components/schemas/DocumentRelation"}}},"required":["id","number","is_draft","date","issuer","translations","total","total_with_tax","total_discount","creation_source","calculation_mode","taxes","currency_code","entity_id","date_year","created_at","updated_at","items"],"description":"Estimate or proforma invoice document"},"EstimateItem":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"type":{"type":["string","null"],"enum":["separator",null],"description":"Item type. null = regular line item, 'separator' = visual section header."},"name":{"type":"string","maxLength":500},"description":{"type":["string","null"]},"classification":{"type":["string","null"],"enum":["product","service","advance",null],"description":"Item classification used for Portugal SAF-T product typing.","example":"service"},"price":{"type":["number","null"],"description":"Per-unit net price before tax in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. Always stores net price. Null for separator items.","example":100},"gross_price":{"type":["number","null"],"description":"Per-unit gross price including tax in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents.\nOnly present if user originally sent gross price.\nUse gross pricing to keep invoice totals stable when VIES reverse charge is applied.","example":122},"quantity":{"type":["number","null"],"description":"Item quantity. Null for separator items.","example":1},"unit":{"type":["string","null"],"description":"Display unit for this line item. E-invoicing XML unit output may be overridden by `e_invoicing.unit_code`.","example":"hours"},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemEInvoicingData"},{"type":"null"}],"description":"Line-level e-invoicing options for XML output."},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentItemTax"},"description":"Applied taxes (provide rate to create new tax, or tax_id to use existing tax)"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/LineDiscount"},"maxItems":5,"description":"Line discounts (max 5) in request order. In `b2b_standard`, percentage discounts are calculated from the original line subtotal and fixed amounts are summed before tax. In `b2c_gross_discount`, discounts are applied sequentially to the running gross subtotal.","example":[{"value":10,"type":"percent"}]},"total":{"type":["number","null"],"description":"Line total before tax in the document currency's major unit. Null for separator items.","example":100},"total_with_tax":{"type":["number","null"],"description":"Line total after tax in the document currency's major unit. Null for separator items.","example":122},"total_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"total_with_tax_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"estimate_id":{"type":["string","null"],"maxLength":36},"advance_invoice_id":{"type":["string","null"],"maxLength":36},"delivery_note_id":{"type":["string","null"],"maxLength":36},"expense_id":{"type":["string","null"],"maxLength":36},"item_id":{"type":["string","null"],"maxLength":36},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"revenue_recognition":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemRevenueRecognition"},{"type":"null"}],"description":"Optional line-level revenue recognition override."},"translations":{"$ref":"#/components/schemas/DocumentItemTranslations"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"financial_category_id":{"type":["string","null"],"description":"Reporting financial category assigned to this document line.","example":"fcat_abc123"}},"required":["id","name","description","taxes","discounts","translations","created_at","updated_at"]},"CreateEstimate":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtDocumentInput"},{"type":"null"}]},"date_valid_till":{"type":["string","null"],"description":"Estimate validity date in YYYY-MM-DD format","example":"2024-02-15"},"title_type":{"type":["string","null"],"enum":["estimate","proforma_invoice",null],"description":"Display name variant for the document. 'estimate' renders as 'Estimate' (Ponudba/Ponuda), 'proforma_invoice' renders as 'Proforma invoice' (Predračun).","example":"estimate"},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the estimate. At least one item is required."},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122}},"required":["items"],"additionalProperties":false},"CustomCreateEstimate":{"type":"object","properties":{"is_draft":{"type":["boolean","null"]},"date":{"type":["string","null"]},"issuer":{"anyOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"type":"null"}]},"business_unit_id":{"type":["string","null"]},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"]},"payment_terms":{"type":["string","null"]},"tax_clause":{"type":["string","null"]},"footer":{"type":["string","null"]},"signature":{"type":["string","null"]},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"]},"pt":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"date_valid_till":{"type":["string","null"]},"title_type":{"type":["string","null"],"enum":["estimate","proforma_invoice",null]},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"items":{"type":"array","items":{"$ref":"#/components/schemas/CustomDocumentItem"},"minItems":1,"description":"Line items with pre-calculated totals. At least one item is required."},"total":{"type":"number","description":"Pre-calculated document total (before tax).","example":1000},"total_with_tax":{"type":"number","description":"Pre-calculated document total (after tax).","example":1220},"total_discount":{"type":["number","null"],"description":"Pre-calculated total net discount amount. Defaults to 0 if not provided."},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"},"description":"Pre-calculated tax summary. If not provided, defaults to empty array."},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]}},"required":["items","total","total_with_tax"],"additionalProperties":false},"EstimateList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Estimate"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"UpdateEstimate":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date (YYYY-MM-DD or ISO datetime format).","example":"2024-01-15"},"issuer":{"allOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"description":"Issuer information snapshot."}]},"business_unit_id":{"type":["string","null"],"description":"Selected business unit. Set to null to revert the document to the main entity. When provided without `business_unit`, the document business-unit snapshot is populated from the saved business unit."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Set to null to remove customer reference."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the document. If provided, replaces ALL existing items. Standard documents recalculate totals. Custom documents created with pre-calculated totals preserve existing totals when item financial inputs are unchanged."},"note":{"type":["string","null"],"description":"Document note/memo. Set to null to clear."},"payment_terms":{"type":["string","null"],"description":"Payment terms text. Set to null to clear."},"tax_clause":{"type":["string","null"],"description":"Tax clause text. Set to null to clear."},"footer":{"type":["string","null"],"description":"Footer text. Set to null to clear."},"signature":{"type":["string","null"],"description":"Signature text (e.g. 'John Smith, CEO'). Set to null to clear."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Translated user-authored document content. Set to null to clear all translations.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"currency_code":{"type":"string","description":"Currency code (ISO 4217, 3 characters). Changing currency triggers exchange rate recalculation.","example":"EUR"},"reference":{"type":["string","null"],"maxLength":100,"description":"Custom reference (e.g., purchase order number, payment reference). When set, overrides the auto-generated UPN payment reference for Slovenian invoices. Set to null to clear."},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Custom metadata object. Set to null to clear."},"change_reason":{"type":"string","maxLength":500,"description":"Reason for the change. Stored in version history for audit trail.","example":"Corrected customer address"},"date_valid_till":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Estimate validity date (YYYY-MM-DD or ISO datetime format). Set to null to clear.","example":"2024-02-28"},"title_type":{"type":"string","enum":["estimate","proforma_invoice"],"description":"Document title type. \"estimate\" or \"proforma_invoice\".","example":"estimate"},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]}},"additionalProperties":false},"PartialEstimatePreview":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtDocumentInput"},{"type":"null"}]},"date_valid_till":{"type":["string","null"],"description":"Estimate validity date in YYYY-MM-DD format","example":"2024-02-15"},"title_type":{"type":["string","null"],"enum":["estimate","proforma_invoice",null],"description":"Display name variant for the document. 'estimate' renders as 'Estimate' (Ponudba/Ponuda), 'proforma_invoice' renders as 'Proforma invoice' (Predračun).","example":"estimate"},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["separator"]},"name":{"type":"string"},"quantity":{"type":"number"},"price":{"type":"number"},"gross_price":{"type":"number"},"description":{"type":"string"},"unit":{"type":"string"},"discounts":{"type":"array","items":{"type":"object","properties":{"value":{"type":"number"},"type":{"type":"string","enum":["percent","amount"]}},"required":["value"]}},"taxes":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"},"tax_id":{"type":"string"}}}},"total":{"type":"number"},"total_with_tax":{"type":"number"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"minItems":1},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"creation_source":{"type":"string","enum":["custom"]},"total":{"type":"number"},"total_with_tax":{"type":"number"},"total_discount":{"type":["number","null"]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"}}},"required":["items"],"additionalProperties":false},"CompleteEstimatePreview":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtDocumentInput"},{"type":"null"}]},"date_valid_till":{"type":["string","null"],"description":"Estimate validity date in YYYY-MM-DD format","example":"2024-02-15"},"title_type":{"type":["string","null"],"enum":["estimate","proforma_invoice",null],"description":"Display name variant for the document. 'estimate' renders as 'Estimate' (Ponudba/Ponuda), 'proforma_invoice' renders as 'Proforma invoice' (Predračun).","example":"estimate"},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the estimate. At least one item is required."},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"creation_source":{"type":"string","enum":["custom"]},"total":{"type":"number"},"total_with_tax":{"type":"number"},"total_discount":{"type":["number","null"]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"}}},"required":["items"],"additionalProperties":false},"CreditNote":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"number":{"type":"string","maxLength":100},"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","format":"date-time","description":"Date the credit note was created (ISO 8601 datetime at midnight UTC)"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/BusinessUnitSnapshot"},{"type":"null"}],"description":"Frozen business-unit snapshot used for stable rendering and historical accuracy."},"customer_id":{"type":["string","null"],"maxLength":36},"customer":{"anyOf":[{"$ref":"#/components/schemas/DocumentCustomer"},{"type":"null"}],"description":"Customer information snapshot stored on the document. Null means no customer. When present, known customer fields are returned with null for omitted values."},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"$ref":"#/components/schemas/DocumentTranslations"},"total":{"type":"number","description":"Document total before tax in the currency's major unit. For EUR, `29.90` means €29.90, not 2,990 cents."},"total_with_tax":{"type":"number","description":"Document total after tax in the currency's major unit. For EUR, `29.90` means €29.90, not 2,990 cents."},"total_discount":{"type":"number","description":"Document discount total in the currency's major unit, stored as a net-equivalent amount for compatibility. In `b2b_standard`, this is the net value of line-item discounts applied before tax. In `b2c_gross_discount`, gross discounts are converted back to their net-equivalent value here. 0 when no discounts applied."},"creation_source":{"$ref":"#/components/schemas/CreationSource"},"calculation_mode":{"type":"string","enum":["b2b_standard","b2c_gross_discount"],"description":"Resolved calculation mode used for this document. Stored on the document so recalculation and rendering remain stable even if entity defaults change later.","example":"b2b_standard"},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"},"description":"Applied taxes summary"},"currency_code":{"type":"string","maxLength":3},"entity_id":{"type":"string","maxLength":36},"date_year":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"shareable_id":{"type":["string","null"],"maxLength":100},"voided_at":{"type":["string","null"],"format":"date-time"},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export",null],"description":"Transaction type for VAT purposes (domestic, intra_eu_b2b, intra_eu_b2c, export). Always determined based on issuer/customer countries."},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"exchange_rate":{"anyOf":[{"$ref":"#/components/schemas/ExchangeRate"},{"type":"null"}],"description":"Currency exchange rate information if conversion was applied"},"total_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"total_with_tax_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"rounding_correction":{"type":["number","null"],"description":"Rounding correction in the currency's major unit, applied to reconcile differences between calculated total_with_tax and expected_total_with_tax. Only present when expected_total_with_tax was provided during creation."},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogData"},{"type":"null"}],"description":"e-SLOG 2.0 validation data for Slovenian electronic invoices. Only applicable when entity.country_code = 'SI' and eslog validation is enabled."},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"vies":{"anyOf":[{"$ref":"#/components/schemas/ViesDocumentData"},{"type":"null"},{"type":"null"}],"description":"VIES validation info including any warnings and skipped indicator for audit trail"},"deleted_at":{"type":["string","null"],"format":"date-time","description":"Timestamp when the document was soft-deleted. Null if not deleted."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"total_paid":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_due":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"paid_in_full":{"type":"boolean"},"furs":{"anyOf":[{"$ref":"#/components/schemas/FursFiscalizationResponse"},{"type":"null"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/FinaFiscalizationResponse"},{"type":"null"}]},"pt":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"xrechnung":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingData"},{"type":"null"}],"description":"Server-managed German XRechnung validation data stored on credit notes. Only applicable when entity.country_code = 'DE' and XRechnung is enabled. Buyer reference / Leitweg-ID input is stored on customer.e_invoicing.buyer_reference."},"zugferd":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingData"},{"type":"null"}],"description":"Server-managed German ZUGFeRD/Factur-X validation data stored on credit notes. Only applicable when entity.country_code = 'DE' and ZUGFeRD is enabled. Buyer reference / Leitweg-ID input is stored on customer.e_invoicing.buyer_reference."},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpData"},{"type":"null"}],"description":"UJP package validation data for Slovenian credit-note exports. Only applicable when entity.country_code = 'SI' and UJP validation is enabled."},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreditNoteItem"}},"document_relations":{"type":"array","items":{"$ref":"#/components/schemas/DocumentRelation"}}},"required":["id","number","is_draft","date","issuer","translations","total","total_with_tax","total_discount","creation_source","calculation_mode","taxes","currency_code","entity_id","date_year","created_at","updated_at","total_paid","total_due","paid_in_full","items"],"description":"Credit note document for refunds/corrections"},"CreditNoteItem":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"type":{"type":["string","null"],"enum":["separator",null],"description":"Item type. null = regular line item, 'separator' = visual section header."},"name":{"type":"string","maxLength":500},"description":{"type":["string","null"]},"classification":{"type":["string","null"],"enum":["product","service","advance",null],"description":"Item classification used for Portugal SAF-T product typing.","example":"service"},"price":{"type":["number","null"],"description":"Per-unit net price before tax in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. Always stores net price. Null for separator items.","example":100},"gross_price":{"type":["number","null"],"description":"Per-unit gross price including tax in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents.\nOnly present if user originally sent gross price.\nUse gross pricing to keep invoice totals stable when VIES reverse charge is applied.","example":122},"quantity":{"type":["number","null"],"description":"Item quantity. Null for separator items.","example":1},"unit":{"type":["string","null"],"description":"Display unit for this line item. E-invoicing XML unit output may be overridden by `e_invoicing.unit_code`.","example":"hours"},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemEInvoicingData"},{"type":"null"}],"description":"Line-level e-invoicing options for XML output."},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentItemTax"},"description":"Applied taxes (provide rate to create new tax, or tax_id to use existing tax)"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/LineDiscount"},"maxItems":5,"description":"Line discounts (max 5) in request order. In `b2b_standard`, percentage discounts are calculated from the original line subtotal and fixed amounts are summed before tax. In `b2c_gross_discount`, discounts are applied sequentially to the running gross subtotal.","example":[{"value":10,"type":"percent"}]},"total":{"type":["number","null"],"description":"Line total before tax in the document currency's major unit. Null for separator items.","example":100},"total_with_tax":{"type":["number","null"],"description":"Line total after tax in the document currency's major unit. Null for separator items.","example":122},"total_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"total_with_tax_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"credit_note_id":{"type":["string","null"],"maxLength":36},"advance_invoice_id":{"type":["string","null"],"maxLength":36},"delivery_note_id":{"type":["string","null"],"maxLength":36},"expense_id":{"type":["string","null"],"maxLength":36},"item_id":{"type":["string","null"],"maxLength":36},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"revenue_recognition":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemRevenueRecognition"},{"type":"null"}],"description":"Optional line-level revenue recognition override."},"translations":{"$ref":"#/components/schemas/DocumentItemTranslations"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"financial_category_id":{"type":["string","null"],"description":"Reporting financial category assigned to this document line.","example":"fcat_abc123"}},"required":["id","name","description","taxes","discounts","translations","created_at","updated_at"]},"CreateCreditNote":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtDocumentInput"},{"type":"null"}]},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the credit note. At least one item is required."},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this credit note to invoices. Accepts invoice IDs (inv_xxx). Creates 'credit_for' document relations. If no payment is specified and linked invoices have remaining balance, automatically applies the credit note to the invoices.","example":["inv_abc123"]},"payments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentPayment"},"description":"Optional payments to record with the credit note. If amounts are not provided, the credit note total is split equally among all payments. Automatically updates credit note payment status."},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"furs":{"anyOf":[{"$ref":"#/components/schemas/CreateFursDocumentData"},{"type":"null"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/CreateFinaInvoiceData"},{"type":"null"}]},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentEInvoicingSendInput"},{"type":"null"}]},"xrechnung":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"zugferd":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpInput"},{"type":"null"}]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122}},"required":["items"],"additionalProperties":false},"CustomCreateCreditNote":{"type":"object","properties":{"is_draft":{"type":["boolean","null"]},"date":{"type":["string","null"]},"issuer":{"anyOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"type":"null"}]},"business_unit_id":{"type":["string","null"]},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"]},"payment_terms":{"type":["string","null"]},"tax_clause":{"type":["string","null"]},"footer":{"type":["string","null"]},"signature":{"type":["string","null"]},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"]},"pt":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"date_service":{"type":["string","null"]},"date_service_to":{"type":["string","null"]},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"items":{"type":"array","items":{"$ref":"#/components/schemas/CustomDocumentItem"},"minItems":1,"description":"Line items with pre-calculated totals. At least one item is required."},"total":{"type":"number","description":"Pre-calculated document total (before tax).","example":1000},"total_with_tax":{"type":"number","description":"Pre-calculated document total (after tax).","example":1220},"total_discount":{"type":["number","null"],"description":"Pre-calculated total net discount amount. Defaults to 0 if not provided."},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"},"description":"Pre-calculated tax summary. If not provided, defaults to empty array."},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this credit note to invoices.","example":["inv_abc123"]},"payments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentPayment"},"description":"Optional payments to record with the credit note. If amounts are not provided, the credit note total is split equally among all payments. Automatically updates credit note payment status."},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"furs":{"anyOf":[{"$ref":"#/components/schemas/CreateFursDocumentData"},{"type":"null"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/CreateFinaInvoiceData"},{"type":"null"}]},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentEInvoicingSendInput"},{"type":"null"}]},"xrechnung":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"zugferd":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpInput"},{"type":"null"}]}},"required":["items","total","total_with_tax"],"additionalProperties":false},"CreditNoteList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CreditNote"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"UpdateCreditNote":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date (YYYY-MM-DD or ISO datetime format).","example":"2024-01-15"},"issuer":{"allOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"description":"Issuer information snapshot."}]},"business_unit_id":{"type":["string","null"],"description":"Selected business unit. Set to null to revert the document to the main entity. When provided without `business_unit`, the document business-unit snapshot is populated from the saved business unit."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Set to null to remove customer reference."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the document. If provided, replaces ALL existing items. Standard documents recalculate totals. Custom documents created with pre-calculated totals preserve existing totals when item financial inputs are unchanged."},"note":{"type":["string","null"],"description":"Document note/memo. Set to null to clear."},"payment_terms":{"type":["string","null"],"description":"Payment terms text. Set to null to clear."},"tax_clause":{"type":["string","null"],"description":"Tax clause text. Set to null to clear."},"footer":{"type":["string","null"],"description":"Footer text. Set to null to clear."},"signature":{"type":["string","null"],"description":"Signature text (e.g. 'John Smith, CEO'). Set to null to clear."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Translated user-authored document content. Set to null to clear all translations.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"currency_code":{"type":"string","description":"Currency code (ISO 4217, 3 characters). Changing currency triggers exchange rate recalculation.","example":"EUR"},"reference":{"type":["string","null"],"maxLength":100,"description":"Custom reference (e.g., purchase order number, payment reference). When set, overrides the auto-generated UPN payment reference for Slovenian invoices. Set to null to clear."},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Custom metadata object. Set to null to clear."},"change_reason":{"type":"string","maxLength":500,"description":"Reason for the change. Stored in version history for audit trail.","example":"Corrected customer address"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service/work date or start of service period. Set to null to clear.","example":"2024-01-01"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"End of service period (if different from date_service). Set to null to clear.","example":"2024-01-31"},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this credit note to invoices. Replaces existing links. Accepts invoice IDs (inv_xxx).","example":["inv_abc123"]},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]},"xrechnung":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"zugferd":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpInput"},{"type":"null"}]}},"additionalProperties":false},"PartialCreditNotePreview":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtDocumentInput"},{"type":"null"}]},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"items":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["separator"]},"name":{"type":"string"},"quantity":{"type":"number"},"price":{"type":"number"},"gross_price":{"type":"number"},"description":{"type":"string"},"unit":{"type":"string"},"discounts":{"type":"array","items":{"type":"object","properties":{"value":{"type":"number"},"type":{"type":"string","enum":["percent","amount"]}},"required":["value"]}},"taxes":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"},"tax_id":{"type":"string"}}}},"total":{"type":"number"},"total_with_tax":{"type":"number"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"minItems":1},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this credit note to invoices. Accepts invoice IDs (inv_xxx). Creates 'credit_for' document relations. If no payment is specified and linked invoices have remaining balance, automatically applies the credit note to the invoices.","example":["inv_abc123"]},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/CreateFinaInvoiceData"},{"type":"null"}]},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentEInvoicingSendInput"},{"type":"null"}]},"xrechnung":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"zugferd":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpInput"},{"type":"null"}]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"creation_source":{"type":"string","enum":["custom"]},"total":{"type":"number"},"total_with_tax":{"type":"number"},"total_discount":{"type":["number","null"]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"}}},"required":["items"],"additionalProperties":false},"CompleteCreditNotePreview":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtDocumentInput"},{"type":"null"}]},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the credit note. At least one item is required."},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this credit note to invoices. Accepts invoice IDs (inv_xxx). Creates 'credit_for' document relations. If no payment is specified and linked invoices have remaining balance, automatically applies the credit note to the invoices.","example":["inv_abc123"]},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/CreateFinaInvoiceData"},{"type":"null"}]},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentEInvoicingSendInput"},{"type":"null"}]},"xrechnung":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"zugferd":{"anyOf":[{"$ref":"#/components/schemas/GermanEInvoicingInput"},{"type":"null"}]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpInput"},{"type":"null"}]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"creation_source":{"type":"string","enum":["custom"]},"total":{"type":"number"},"total_with_tax":{"type":"number"},"total_discount":{"type":["number","null"]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"}}},"required":["items"],"additionalProperties":false},"AdvanceInvoice":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"number":{"type":"string","maxLength":100},"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","format":"date-time","description":"Date the advance invoice was created (ISO 8601 datetime at midnight UTC)"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/BusinessUnitSnapshot"},{"type":"null"}],"description":"Frozen business-unit snapshot used for stable rendering and historical accuracy."},"customer_id":{"type":["string","null"],"maxLength":36},"customer":{"anyOf":[{"$ref":"#/components/schemas/DocumentCustomer"},{"type":"null"}],"description":"Customer information snapshot stored on the document. Null means no customer. When present, known customer fields are returned with null for omitted values."},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"$ref":"#/components/schemas/DocumentTranslations"},"total":{"type":"number","description":"Document total before tax in the currency's major unit. For EUR, `29.90` means €29.90, not 2,990 cents."},"total_with_tax":{"type":"number","description":"Document total after tax in the currency's major unit. For EUR, `29.90` means €29.90, not 2,990 cents."},"total_discount":{"type":"number","description":"Document discount total in the currency's major unit, stored as a net-equivalent amount for compatibility. In `b2b_standard`, this is the net value of line-item discounts applied before tax. In `b2c_gross_discount`, gross discounts are converted back to their net-equivalent value here. 0 when no discounts applied."},"creation_source":{"$ref":"#/components/schemas/CreationSource"},"calculation_mode":{"type":"string","enum":["b2b_standard","b2c_gross_discount"],"description":"Resolved calculation mode used for this document. Stored on the document so recalculation and rendering remain stable even if entity defaults change later.","example":"b2b_standard"},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"},"description":"Applied taxes summary"},"currency_code":{"type":"string","maxLength":3},"entity_id":{"type":"string","maxLength":36},"date_year":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"shareable_id":{"type":["string","null"],"maxLength":100},"voided_at":{"type":["string","null"],"format":"date-time"},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export",null],"description":"Transaction type for VAT purposes (domestic, intra_eu_b2b, intra_eu_b2c, export). Always determined based on issuer/customer countries."},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"exchange_rate":{"anyOf":[{"$ref":"#/components/schemas/ExchangeRate"},{"type":"null"}],"description":"Currency exchange rate information if conversion was applied"},"total_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"total_with_tax_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"rounding_correction":{"type":["number","null"],"description":"Rounding correction in the currency's major unit, applied to reconcile differences between calculated total_with_tax and expected_total_with_tax. Only present when expected_total_with_tax was provided during creation."},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogData"},{"type":"null"}],"description":"e-SLOG 2.0 validation data for Slovenian electronic invoices. Only applicable when entity.country_code = 'SI' and eslog validation is enabled."},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"vies":{"anyOf":[{"$ref":"#/components/schemas/ViesDocumentData"},{"type":"null"},{"type":"null"}],"description":"VIES validation info including any warnings and skipped indicator for audit trail"},"deleted_at":{"type":["string","null"],"format":"date-time","description":"Timestamp when the document was soft-deleted. Null if not deleted."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"total_paid":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_due":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"paid_in_full":{"type":"boolean"},"furs":{"anyOf":[{"$ref":"#/components/schemas/FursFiscalizationResponse"},{"type":"null"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/FinaFiscalizationResponse"},{"type":"null"}]},"pt":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdvanceInvoiceItem"}},"document_relations":{"type":"array","items":{"$ref":"#/components/schemas/DocumentRelation"}}},"required":["id","number","is_draft","date","issuer","translations","total","total_with_tax","total_discount","creation_source","calculation_mode","taxes","currency_code","entity_id","date_year","created_at","updated_at","total_paid","total_due","paid_in_full","items"],"description":"Advance invoice for prepayments"},"AdvanceInvoiceItem":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"type":{"type":["string","null"],"enum":["separator",null],"description":"Item type. null = regular line item, 'separator' = visual section header."},"name":{"type":"string","maxLength":500},"description":{"type":["string","null"]},"classification":{"type":["string","null"],"enum":["product","service","advance",null],"description":"Item classification used for Portugal SAF-T product typing.","example":"service"},"price":{"type":["number","null"],"description":"Per-unit net price before tax in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. Always stores net price. Null for separator items.","example":100},"gross_price":{"type":["number","null"],"description":"Per-unit gross price including tax in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents.\nOnly present if user originally sent gross price.\nUse gross pricing to keep invoice totals stable when VIES reverse charge is applied.","example":122},"quantity":{"type":["number","null"],"description":"Item quantity. Null for separator items.","example":1},"unit":{"type":["string","null"],"description":"Display unit for this line item. E-invoicing XML unit output may be overridden by `e_invoicing.unit_code`.","example":"hours"},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemEInvoicingData"},{"type":"null"}],"description":"Line-level e-invoicing options for XML output."},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentItemTax"},"description":"Applied taxes (provide rate to create new tax, or tax_id to use existing tax)"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/LineDiscount"},"maxItems":5,"description":"Line discounts (max 5) in request order. In `b2b_standard`, percentage discounts are calculated from the original line subtotal and fixed amounts are summed before tax. In `b2c_gross_discount`, discounts are applied sequentially to the running gross subtotal.","example":[{"value":10,"type":"percent"}]},"total":{"type":["number","null"],"description":"Line total before tax in the document currency's major unit. Null for separator items.","example":100},"total_with_tax":{"type":["number","null"],"description":"Line total after tax in the document currency's major unit. Null for separator items.","example":122},"total_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"total_with_tax_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"advance_invoice_id":{"type":["string","null"],"maxLength":36},"delivery_note_id":{"type":["string","null"],"maxLength":36},"expense_id":{"type":["string","null"],"maxLength":36},"item_id":{"type":["string","null"],"maxLength":36},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"revenue_recognition":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemRevenueRecognition"},{"type":"null"}],"description":"Optional line-level revenue recognition override."},"translations":{"$ref":"#/components/schemas/DocumentItemTranslations"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"financial_category_id":{"type":["string","null"],"description":"Reporting financial category assigned to this document line.","example":"fcat_abc123"}},"required":["id","name","description","taxes","discounts","translations","created_at","updated_at"]},"CreateAdvanceInvoice":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtDocumentInput"},{"type":"null"}]},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the advance invoice. At least one item is required."},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this advance invoice to other documents. Creates document relations automatically.","example":[]},"payments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentPayment"},"description":"Payments to record with the advance invoice. Required for non-draft advance invoices. If amounts are not provided, the total is split equally. Automatically updates payment status."},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"furs":{"anyOf":[{"$ref":"#/components/schemas/CreateFursDocumentData"},{"type":"null"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/CreateFinaInvoiceData"},{"type":"null"}]},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122}},"required":["items"],"additionalProperties":false},"CustomCreateAdvanceInvoice":{"type":"object","properties":{"is_draft":{"type":["boolean","null"]},"date":{"type":["string","null"]},"issuer":{"anyOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"type":"null"}]},"business_unit_id":{"type":["string","null"]},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"]},"tax_clause":{"type":["string","null"]},"footer":{"type":["string","null"]},"signature":{"type":["string","null"]},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"]},"pt":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"items":{"type":"array","items":{"$ref":"#/components/schemas/CustomDocumentItem"},"minItems":1,"description":"Line items with pre-calculated totals. At least one item is required."},"total":{"type":"number","description":"Pre-calculated document total (before tax).","example":1000},"total_with_tax":{"type":"number","description":"Pre-calculated document total (after tax).","example":1220},"total_discount":{"type":["number","null"],"description":"Pre-calculated total net discount amount. Defaults to 0 if not provided."},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"},"description":"Pre-calculated tax summary. If not provided, defaults to empty array."},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this advance invoice to other documents.","example":[]},"payments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentPayment"},"description":"Payments to record with the advance invoice. Required for non-draft advance invoices. If amounts are not provided, the total is split equally. Automatically updates payment status."},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"furs":{"anyOf":[{"$ref":"#/components/schemas/CreateFursDocumentData"},{"type":"null"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/CreateFinaInvoiceData"},{"type":"null"}]},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]}},"required":["items","total","total_with_tax"],"additionalProperties":false},"AdvanceInvoiceList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdvanceInvoice"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"UpdateAdvanceInvoice":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date (YYYY-MM-DD or ISO datetime format).","example":"2024-01-15"},"issuer":{"allOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"description":"Issuer information snapshot."}]},"business_unit_id":{"type":["string","null"],"description":"Selected business unit. Set to null to revert the document to the main entity. When provided without `business_unit`, the document business-unit snapshot is populated from the saved business unit."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Set to null to remove customer reference."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the document. If provided, replaces ALL existing items. Standard documents recalculate totals. Custom documents created with pre-calculated totals preserve existing totals when item financial inputs are unchanged."},"note":{"type":["string","null"],"description":"Document note/memo. Set to null to clear."},"tax_clause":{"type":["string","null"],"description":"Tax clause text. Set to null to clear."},"footer":{"type":["string","null"],"description":"Footer text. Set to null to clear."},"signature":{"type":["string","null"],"description":"Signature text (e.g. 'John Smith, CEO'). Set to null to clear."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Translated user-authored document content. Set to null to clear all translations.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"currency_code":{"type":"string","description":"Currency code (ISO 4217, 3 characters). Changing currency triggers exchange rate recalculation.","example":"EUR"},"reference":{"type":["string","null"],"maxLength":100,"description":"Custom reference (e.g., purchase order number, payment reference). When set, overrides the auto-generated UPN payment reference for Slovenian invoices. Set to null to clear."},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Custom metadata object. Set to null to clear."},"change_reason":{"type":"string","maxLength":500,"description":"Reason for the change. Stored in version history for audit trail.","example":"Corrected customer address"},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this advance invoice to other documents. Replaces existing links. Accepts invoice IDs (inv_xxx).","example":["inv_abc123"]},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]}},"additionalProperties":false},"PartialAdvanceInvoicePreview":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtDocumentInput"},{"type":"null"}]},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["separator"]},"name":{"type":"string"},"quantity":{"type":"number"},"price":{"type":"number"},"gross_price":{"type":"number"},"description":{"type":"string"},"unit":{"type":"string"},"discounts":{"type":"array","items":{"type":"object","properties":{"value":{"type":"number"},"type":{"type":"string","enum":["percent","amount"]}},"required":["value"]}},"taxes":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"},"tax_id":{"type":"string"}}}},"total":{"type":"number"},"total_with_tax":{"type":"number"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"minItems":1},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this advance invoice to other documents. Creates document relations automatically.","example":[]},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/CreateFinaInvoiceData"},{"type":"null"}]},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"creation_source":{"type":"string","enum":["custom"]},"total":{"type":"number"},"total_with_tax":{"type":"number"},"total_discount":{"type":["number","null"]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"}}},"required":["items"],"additionalProperties":false},"CompleteAdvanceInvoicePreview":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtDocumentInput"},{"type":"null"}]},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the advance invoice. At least one item is required."},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this advance invoice to other documents. Creates document relations automatically.","example":[]},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/CreateFinaInvoiceData"},{"type":"null"}]},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"creation_source":{"type":"string","enum":["custom"]},"total":{"type":"number"},"total_with_tax":{"type":"number"},"total_discount":{"type":["number","null"]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"}}},"required":["items"],"additionalProperties":false},"DeliveryNote":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"number":{"type":"string","maxLength":100},"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","format":"date-time","description":"Date the delivery note was created (ISO 8601 datetime at midnight UTC)"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/BusinessUnitSnapshot"},{"type":"null"}],"description":"Frozen business-unit snapshot used for stable rendering and historical accuracy."},"customer_id":{"type":["string","null"],"maxLength":36},"customer":{"anyOf":[{"$ref":"#/components/schemas/DocumentCustomer"},{"type":"null"}],"description":"Customer information snapshot stored on the document. Null means no customer. When present, known customer fields are returned with null for omitted values."},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"$ref":"#/components/schemas/DocumentTranslations"},"total":{"type":"number","description":"Document total before tax in the currency's major unit. For EUR, `29.90` means €29.90, not 2,990 cents."},"total_with_tax":{"type":"number","description":"Document total after tax in the currency's major unit. For EUR, `29.90` means €29.90, not 2,990 cents."},"total_discount":{"type":"number","description":"Document discount total in the currency's major unit, stored as a net-equivalent amount for compatibility. In `b2b_standard`, this is the net value of line-item discounts applied before tax. In `b2c_gross_discount`, gross discounts are converted back to their net-equivalent value here. 0 when no discounts applied."},"creation_source":{"$ref":"#/components/schemas/CreationSource"},"calculation_mode":{"type":"string","enum":["b2b_standard","b2c_gross_discount"],"description":"Resolved calculation mode used for this document. Stored on the document so recalculation and rendering remain stable even if entity defaults change later.","example":"b2b_standard"},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"},"description":"Applied taxes summary"},"currency_code":{"type":"string","maxLength":3},"entity_id":{"type":"string","maxLength":36},"date_year":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"shareable_id":{"type":["string","null"],"maxLength":100},"voided_at":{"type":["string","null"],"format":"date-time"},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export",null],"description":"Transaction type for VAT purposes (domestic, intra_eu_b2b, intra_eu_b2c, export). Always determined based on issuer/customer countries."},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"exchange_rate":{"anyOf":[{"$ref":"#/components/schemas/ExchangeRate"},{"type":"null"}],"description":"Currency exchange rate information if conversion was applied"},"total_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"total_with_tax_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"rounding_correction":{"type":["number","null"],"description":"Rounding correction in the currency's major unit, applied to reconcile differences between calculated total_with_tax and expected_total_with_tax. Only present when expected_total_with_tax was provided during creation."},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogData"},{"type":"null"}],"description":"e-SLOG 2.0 validation data for Slovenian electronic invoices. Only applicable when entity.country_code = 'SI' and eslog validation is enabled."},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"vies":{"anyOf":[{"$ref":"#/components/schemas/ViesDocumentData"},{"type":"null"},{"type":"null"}],"description":"VIES validation info including any warnings and skipped indicator for audit trail"},"deleted_at":{"type":["string","null"],"format":"date-time","description":"Timestamp when the document was soft-deleted. Null if not deleted."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"hide_prices":{"type":"boolean","description":"When true, prices and totals are hidden on the document (packing list mode).","example":false},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryNoteItem"}},"document_relations":{"type":"array","items":{"$ref":"#/components/schemas/DocumentRelation"}}},"required":["id","number","is_draft","date","issuer","translations","total","total_with_tax","total_discount","creation_source","calculation_mode","taxes","currency_code","entity_id","date_year","created_at","updated_at","hide_prices","items"],"description":"Delivery note / packing list document"},"DeliveryNoteItem":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"type":{"type":["string","null"],"enum":["separator",null],"description":"Item type. null = regular line item, 'separator' = visual section header."},"name":{"type":"string","maxLength":500},"description":{"type":["string","null"]},"classification":{"type":["string","null"],"enum":["product","service","advance",null],"description":"Item classification used for Portugal SAF-T product typing.","example":"service"},"price":{"type":["number","null"],"description":"Per-unit net price before tax in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. Always stores net price. Null for separator items.","example":100},"gross_price":{"type":["number","null"],"description":"Per-unit gross price including tax in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents.\nOnly present if user originally sent gross price.\nUse gross pricing to keep invoice totals stable when VIES reverse charge is applied.","example":122},"quantity":{"type":["number","null"],"description":"Item quantity. Null for separator items.","example":1},"unit":{"type":["string","null"],"description":"Display unit for this line item. E-invoicing XML unit output may be overridden by `e_invoicing.unit_code`.","example":"hours"},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemEInvoicingData"},{"type":"null"}],"description":"Line-level e-invoicing options for XML output."},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentItemTax"},"description":"Applied taxes (provide rate to create new tax, or tax_id to use existing tax)"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/LineDiscount"},"maxItems":5,"description":"Line discounts (max 5) in request order. In `b2b_standard`, percentage discounts are calculated from the original line subtotal and fixed amounts are summed before tax. In `b2c_gross_discount`, discounts are applied sequentially to the running gross subtotal.","example":[{"value":10,"type":"percent"}]},"total":{"type":["number","null"],"description":"Line total before tax in the document currency's major unit. Null for separator items.","example":100},"total_with_tax":{"type":["number","null"],"description":"Line total after tax in the document currency's major unit. Null for separator items.","example":122},"total_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"total_with_tax_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"delivery_note_id":{"type":["string","null"],"maxLength":36},"expense_id":{"type":["string","null"],"maxLength":36},"item_id":{"type":["string","null"],"maxLength":36},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"revenue_recognition":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemRevenueRecognition"},{"type":"null"}],"description":"Optional line-level revenue recognition override."},"translations":{"$ref":"#/components/schemas/DocumentItemTranslations"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"financial_category_id":{"type":["string","null"],"description":"Reporting financial category assigned to this document line.","example":"fcat_abc123"}},"required":["id","name","description","taxes","discounts","translations","created_at","updated_at"]},"CreateDeliveryNote":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"hide_prices":{"type":"boolean","description":"When true, prices and totals are hidden on the document (packing list mode).","example":false},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the delivery note. At least one item is required."},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this delivery note to other documents. Accepts estimate IDs (est_xxx) or invoice IDs (inv_xxx). Creates document relations automatically.","example":["est_abc123"]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122}},"required":["items"],"additionalProperties":false},"CustomCreateDeliveryNote":{"type":"object","properties":{"is_draft":{"type":["boolean","null"]},"date":{"type":["string","null"]},"issuer":{"anyOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"type":"null"}]},"business_unit_id":{"type":["string","null"]},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"]},"payment_terms":{"type":["string","null"]},"tax_clause":{"type":["string","null"]},"footer":{"type":["string","null"]},"signature":{"type":["string","null"]},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"]},"hide_prices":{"type":["boolean","null"]},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"items":{"type":"array","items":{"$ref":"#/components/schemas/CustomDocumentItem"},"minItems":1,"description":"Line items with pre-calculated totals. At least one item is required."},"total":{"type":"number","description":"Pre-calculated document total (before tax).","example":1000},"total_with_tax":{"type":"number","description":"Pre-calculated document total (after tax).","example":1220},"total_discount":{"type":["number","null"],"description":"Pre-calculated total net discount amount. Defaults to 0 if not provided."},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"},"description":"Pre-calculated tax summary. If not provided, defaults to empty array."},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this delivery note to other documents. Accepts estimate IDs (est_xxx) or invoice IDs (inv_xxx). Creates document relations automatically.","example":["est_abc123"]},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"eslog":{"anyOf":[{"$ref":"#/components/schemas/EslogInput"},{"type":"null"}]}},"required":["items","total","total_with_tax"],"additionalProperties":false},"DeliveryNoteList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryNote"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"UpdateDeliveryNote":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date (YYYY-MM-DD or ISO datetime format).","example":"2024-01-15"},"issuer":{"allOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"description":"Issuer information snapshot."}]},"business_unit_id":{"type":["string","null"],"description":"Selected business unit. Set to null to revert the document to the main entity. When provided without `business_unit`, the document business-unit snapshot is populated from the saved business unit."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Set to null to remove customer reference."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the document. If provided, replaces ALL existing items. Standard documents recalculate totals. Custom documents created with pre-calculated totals preserve existing totals when item financial inputs are unchanged."},"note":{"type":["string","null"],"description":"Document note/memo. Set to null to clear."},"payment_terms":{"type":["string","null"],"description":"Payment terms text. Set to null to clear."},"tax_clause":{"type":["string","null"],"description":"Tax clause text. Set to null to clear."},"footer":{"type":["string","null"],"description":"Footer text. Set to null to clear."},"signature":{"type":["string","null"],"description":"Signature text (e.g. 'John Smith, CEO'). Set to null to clear."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Translated user-authored document content. Set to null to clear all translations.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"currency_code":{"type":"string","description":"Currency code (ISO 4217, 3 characters). Changing currency triggers exchange rate recalculation.","example":"EUR"},"reference":{"type":["string","null"],"maxLength":100,"description":"Custom reference (e.g., purchase order number, payment reference). When set, overrides the auto-generated UPN payment reference for Slovenian invoices. Set to null to clear."},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Custom metadata object. Set to null to clear."},"change_reason":{"type":"string","maxLength":500,"description":"Reason for the change. Stored in version history for audit trail.","example":"Corrected customer address"},"hide_prices":{"type":"boolean","description":"When true, prices and totals are hidden on the document (packing list mode).","example":false},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this delivery note to other documents. Replaces existing links. Accepts invoice IDs (inv_xxx).","example":["inv_abc123"]}},"additionalProperties":false},"PartialDeliveryNotePreview":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"hide_prices":{"type":"boolean","description":"When true, prices and totals are hidden on the document (packing list mode).","example":false},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["separator"]},"name":{"type":"string"},"quantity":{"type":"number"},"price":{"type":"number"},"gross_price":{"type":"number"},"description":{"type":"string"},"unit":{"type":"string"},"discounts":{"type":"array","items":{"type":"object","properties":{"value":{"type":"number"},"type":{"type":"string","enum":["percent","amount"]}},"required":["value"]}},"taxes":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"},"tax_id":{"type":"string"}}}},"total":{"type":"number"},"total_with_tax":{"type":"number"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"minItems":1},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this delivery note to other documents. Accepts estimate IDs (est_xxx) or invoice IDs (inv_xxx). Creates document relations automatically.","example":["est_abc123"]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"creation_source":{"type":"string","enum":["custom"]},"total":{"type":"number"},"total_with_tax":{"type":"number"},"total_discount":{"type":["number","null"]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"}}},"required":["items"],"additionalProperties":false},"CompleteDeliveryNotePreview":{"type":"object","properties":{"is_draft":{"type":"boolean","description":"Whether this is a draft document. Draft documents have no sequential number assigned, skip fiscalization, and can be deleted. Use POST /{documents}/{id}/finalize to assign a number and finalize."},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document date in YYYY-MM-DD format","example":"2024-01-15"},"issuer":{"$ref":"#/components/schemas/DocumentEntity"},"business_unit_id":{"type":["string","null"],"description":"Selected business-unit ID used to derive document presentation and defaults."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}]},"note":{"type":["string","null"],"description":"Note for the document. If not provided, defaults to entity's document-type-specific note setting. Pass empty string to explicitly set no note."},"payment_terms":{"type":["string","null"],"description":"Payment terms for the document. If not provided, defaults to entity's document-type-specific payment terms setting. Pass empty string to explicitly set no terms."},"tax_clause":{"type":["string","null"],"description":"Tax clause for the document. Auto-populated based on transaction type if tax_clause_defaults are configured in entity settings. Pass empty string to explicitly set no clause."},"footer":{"type":["string","null"],"maxLength":500},"signature":{"type":["string","null"],"description":"Signature text for the document (e.g. 'John Smith, CEO'). If not provided, defaults to entity's default_document_signature setting. Pass empty string to explicitly set no signature."},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentTranslations"},{"description":"Translated user-authored document content. Base scalar fields remain the default-language source of truth; these entries are only used when rendering with an explicit non-default language."}]},{"type":"null"}],"description":"Optional or null translated user-authored document content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."}}},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"currency_code":{"type":"string","maxLength":3},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"reference":{"type":["string","null"],"description":"Custom reference for the document (e.g., purchase order number, payment reference). When set, used as the UPN payment reference instead of the auto-generated one."},"hide_prices":{"type":"boolean","description":"When true, prices and totals are hidden on the document (packing list mode).","example":false},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Document due date in YYYY-MM-DD format","example":"2024-02-15"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service date in YYYY-MM-DD format. For invoices and credit notes.","example":"2024-01-15"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z?)?$","description":"Service period end date in YYYY-MM-DD format. For invoices and credit notes. Use with date_service for date ranges.","example":"2024-01-31"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the delivery note. At least one item is required."},"category_assignments":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateDocumentCategoryAssignment"},"description":"Optional document line category assignments. Omit or send null to derive assignments from saved item defaults. Send an empty array to explicitly skip categorization. A single entry without `item_index` applies to all non-separator items.","example":[{"financial_category_id":"fcat_abc123"}]},"linked_documents":{"type":["array","null"],"items":{"type":"string","minLength":1},"description":"Link this delivery note to other documents. Accepts estimate IDs (est_xxx) or invoice IDs (inv_xxx). Creates document relations automatically.","example":["est_abc123"]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"creation_source":{"type":"string","enum":["custom"]},"total":{"type":"number"},"total_with_tax":{"type":"number"},"total_discount":{"type":["number","null"]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"}}},"required":["items"],"additionalProperties":false},"NextDocumentNumber":{"type":"object","properties":{"number":{"type":["string","null"],"description":"Preview of the next document number. Null if cannot be determined.","example":"2025-00042"},"furs":{"type":["object","null"],"properties":{"business_premise_name":{"type":"string","description":"Business premise name used for this preview (Slovenia FURS)","example":"P1"},"electronic_device_name":{"type":"string","description":"Electronic device name used for this preview (Slovenia FURS)","example":"E1"}},"required":["business_premise_name","electronic_device_name"],"description":"FURS (Slovenia) fiscalization info if FURS numbering was used. Null for standard numbering."},"fina":{"type":["object","null"],"properties":{"business_premise_name":{"type":"string","description":"Business premise name used for this preview (Croatia CIS)","example":"MAGE5"},"electronic_device_name":{"type":"string","description":"Electronic device name used for this preview (Croatia CIS)","example":"1"}},"required":["business_premise_name","electronic_device_name"],"description":"FINA (Croatia) CIS fiscalization info if FINA is enabled. Null for standard numbering."},"pt":{"type":["object","null"],"properties":{"series_id":{"type":"string","description":"ATCUD series ID used for the PT preview.","example":"atcud_123"},"series_code":{"type":"string","description":"ATCUD series code used in the PT document number.","example":"FT2026A"},"validation_code":{"type":"string","description":"AT validation code for the selected PT series.","example":"AB12CD34"},"manual":{"type":"boolean","description":"Whether the PT preview uses a manual series.","example":false}},"required":["series_id","series_code","validation_code"],"description":"Portugal ATCUD preview info if PT numbering was used. Null for non-PT numbering."}},"required":["number"]},"DocumentCalculation":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CalculatedItem"},"description":"Calculated line items"},"total":{"type":"number","description":"Document total before tax","example":200},"total_with_tax":{"type":"number","description":"Document total after tax","example":244},"total_discount":{"type":"number","description":"Document discount total stored as a net-equivalent amount for compatibility. In `b2b_standard`, this is the net value of line-item discounts applied before tax. In `b2c_gross_discount`, gross discounts are converted back to their net-equivalent value here."},"calculation_mode":{"type":"string","enum":["b2b_standard","b2c_gross_discount"],"description":"Resolved calculation mode used for the preview after applying the request override or entity default.","example":"b2b_standard"},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentSummaryTax"},"description":"Aggregated tax summary"},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export",null],"description":"Transaction type for VAT purposes. Always determined based on issuer/customer countries, regardless of VIES settings."},"currency_code":{"type":"string","description":"Currency code used for calculation","example":"EUR"},"exchange_rate":{"anyOf":[{"$ref":"#/components/schemas/ExchangeRate"},{"type":"null"}],"description":"Exchange rate if currency conversion was applied"},"total_converted":{"type":["number","null"],"description":"Document total in entity currency"},"total_with_tax_converted":{"type":["number","null"],"description":"Document total with tax in entity currency"},"rounding_correction":{"type":["number","null"],"description":"Rounding correction applied when expected_total_with_tax was provided"},"vies":{"anyOf":[{"$ref":"#/components/schemas/ViesDocumentData"},{"type":"null"}]}},"required":["items","total","total_with_tax","total_discount","calculation_mode","taxes","transaction_type","currency_code","exchange_rate","total_converted","total_with_tax_converted","rounding_correction","vies"]},"CalculatedItem":{"type":"object","properties":{"name":{"type":["string","null"]},"description":{"type":["string","null"]},"type":{"type":["string","null"],"enum":["separator",null]},"price":{"type":["number","null"],"description":"Per-unit net price (before tax)","example":100},"gross_price":{"type":["number","null"],"description":"Per-unit gross price (includes tax)"},"quantity":{"type":["number","null"],"example":1},"unit":{"type":["string","null"]},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemEInvoicingData"},{"type":"null"}],"description":"Line-level e-invoicing options preserved from the preview input."},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentItemTax"}},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/LineDiscount"}},"total":{"type":["number","null"],"description":"Line total before tax","example":100},"total_with_tax":{"type":["number","null"],"description":"Line total after tax","example":122},"total_converted":{"type":["number","null"],"description":"Line total before tax in entity currency"},"total_with_tax_converted":{"type":["number","null"],"description":"Line total after tax in entity currency"}},"required":["name","description","type","price","gross_price","quantity","unit","taxes","discounts","total","total_with_tax","total_converted","total_with_tax_converted"]},"CalculateDocumentPreview":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Document line items to calculate. At least one item is required."},"customer":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentCustomer"},{"type":"null"}],"description":"Customer data. Used for transaction type determination (country-based VAT rules)."},"customer_id":{"type":["string","null"],"description":"Existing customer ID. Alternative to inline customer data."},"business_unit":{"anyOf":[{"$ref":"#/components/schemas/CreateDocumentBusinessUnit"},{"type":"null"}],"description":"Explicit business-unit snapshot. When provided, it is used instead of backfilling from the saved unit."},"business_unit_id":{"type":["string","null"],"description":"Existing business-unit ID. Alternative to inline business-unit snapshot."},"currency_code":{"type":["string","null"],"description":"Currency code (ISO 4217). Defaults to entity's currency if not provided.","example":"EUR"},"date":{"type":["string","null"],"description":"Document date (YYYY-MM-DD). Used for tax rate date resolution. Defaults to today.","example":"2025-01-15"},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122}},"required":["items"]},"GenericDocument":{},"FinalizeDocumentBody":{"type":"object","properties":{"furs":{"anyOf":[{"$ref":"#/components/schemas/CreateFursDocumentData"},{"type":"null"}]},"fina":{"anyOf":[{"$ref":"#/components/schemas/CreateFinaInvoiceData"},{"type":"null"}]}}},"FiscalizeDocumentBody":{"type":"object","properties":{"business_premise_name":{"type":["string","null"],"minLength":1,"description":"FURS business premise identifier to use for late/subsequent fiscalization.","example":"P1"},"electronic_device_name":{"type":["string","null"],"minLength":1,"description":"FURS electronic device identifier to use for late/subsequent fiscalization.","example":"E1"},"operator_tax_number":{"type":["string","null"],"minLength":1,"description":"FURS operator tax number. Must be provided together with operator_label unless foreign_operator is true.","example":"12345678"},"operator_label":{"type":["string","null"],"minLength":1,"description":"FURS operator label. Must be provided together with operator_tax_number unless foreign_operator is true.","example":"A.B."},"foreign_operator":{"type":["boolean","null"],"description":"Whether the FURS operator is foreign and has no Slovenian tax number.","example":false}},"additionalProperties":false},"FiscalizedOutputRegistration":{"type":"object","properties":{"print_count":{"type":["integer","null"],"exclusiveMinimum":0,"description":"Reserved output sequence number, or null when the document has no successful fiscalization.","example":2},"fiscalization_provider":{"type":["string","null"],"enum":["furs","fina",null],"description":"Fiscalization payload that owns the output counter.","example":"furs"}},"required":["print_count","fiscalization_provider"]},"EntityApiKeysList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EntityApiKeyListItem"}}},"required":["data"]},"EntityApiKeyListItem":{"allOf":[{"$ref":"#/components/schemas/EntityApiKey"},{"type":"object","properties":{"prefix_hint":{"type":"string","description":"Masked version of the key for display","example":"ek_live_abc...789"}},"required":["prefix_hint"]}]},"EntityApiKey":{"type":"object","properties":{"id":{"type":"string","description":"API key (ek_* prefix for entity-scoped keys)","example":"ek_live_abc123xyz789"},"entity_id":{"type":"string","description":"Entity ID this key is scoped to","example":"ent_xyz789"},"name":{"type":["string","null"],"description":"Friendly name for the API key","example":"Production Integration Key"},"environment":{"type":"string","enum":["live","sandbox"],"description":"Environment the key is valid for"},"created_at":{"type":"string","format":"date-time","description":"When the key was created"},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the key expires, or null if it never expires"}},"required":["id","entity_id","name","environment","created_at","expires_at"]},"StatsQueryBatchResponse":{"type":"array","items":{"$ref":"#/components/schemas/StatsQueryResponse"},"description":"Array of stats query responses, in same order as requests"},"StatsQueryResponse":{"type":"object","properties":{"query":{"$ref":"#/components/schemas/StatsQueryMeta"},"data":{"$ref":"#/components/schemas/StatsQueryData"},"row_count":{"type":"integer","description":"Number of rows returned","example":6}},"required":["query","data","row_count"],"description":"Stats query response with aggregated data"},"StatsQueryMeta":{"type":"object","properties":{"table":{"type":"string"},"date_from":{"type":["string","null"]},"date_to":{"type":["string","null"]},"group_by":{"type":["array","null"],"items":{"type":"string"}}},"required":["table","date_from","date_to","group_by"],"description":"Echo of query parameters"},"StatsQueryData":{"type":"array","items":{"type":"object","additionalProperties":{}},"description":"Query results - shape depends on metrics and group_by"},"StatsQueryBatchRequest":{"type":"array","items":{"$ref":"#/components/schemas/StatsQueryRequest"},"minItems":1,"maxItems":25,"description":"Array of stats query requests (1-25 queries per batch)"},"StatsQueryRequest":{"type":"object","properties":{"metrics":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["count","sum","avg","min","max"],"description":"Aggregation type","example":"sum"},"field":{"type":"string","description":"Field to aggregate (required for sum/avg/min/max)","example":"total_with_tax"},"alias":{"type":"string","description":"Custom name for this metric in the response","example":"revenue"}},"required":["type"]},"minItems":1,"maxItems":10,"description":"Metrics to compute"},"table":{"type":"string","enum":["invoices","estimates","credit_notes","advance_invoices","payments","customers","items","invoice_taxes"],"description":"Table to query","example":"invoices"},"date_from":{"type":"string","description":"Start date (ISO format YYYY-MM-DD)","example":"2024-01-01"},"date_to":{"type":"string","description":"End date (ISO format YYYY-MM-DD)","example":"2024-12-31"},"filters":{"$ref":"#/components/schemas/StatsFilters"},"group_by":{"type":"array","items":{"type":"string"},"maxItems":5,"description":"Fields to group by","example":["month"]},"order_by":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Field to order by","example":"revenue"},"direction":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Sort direction","example":"desc"}},"required":["field"]},"maxItems":3,"description":"Ordering for results"},"limit":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum number of rows to return","example":10}},"required":["metrics","table"],"description":"Stats query request specification"},"StatsFilters":{"type":"object","additionalProperties":{},"description":"Additional filters (field: value pairs)","example":{"is_draft":false,"voided_at":null}},"EntityUsersList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EntityUser"}}},"required":["data"]},"EntityUser":{"type":"object","properties":{"user_id":{"type":"string","description":"User ID","example":"user_abc123"},"entity_id":{"type":"string","description":"Entity ID","example":"entity_xyz789"},"role":{"type":"string","enum":["viewer","editor","admin"],"description":"User role on the entity","example":"editor"},"email":{"type":"string","description":"User email","example":"user@example.com"},"name":{"type":["string","null"],"description":"User name","example":"John Doe"},"invited_by_user_id":{"type":["string","null"],"description":"ID of user who invited this user","example":"user_inviter123"},"created_at":{"type":"string","format":"date-time","description":"When the user was added to the entity"}},"required":["user_id","entity_id","role","email","name","invited_by_user_id","created_at"]},"EntityUsersAccess":{"type":"object","properties":{"account_id":{"type":"string","description":"Account that owns the selected entity","example":"acc_507f1f77bcf86cd799439011"},"account_role":{"type":["string","null"],"enum":["owner","admin","member",null],"description":"Current user's account-level role, when the user is a top-level account user","example":"admin"},"entity_id":{"type":"string","description":"Selected entity ID","example":"ent_507f1f77bcf86cd799439011"},"entity_role":{"type":["string","null"],"enum":["viewer","editor","admin",null],"description":"Current user's entity-level role, when the user is an entity user","example":"editor"},"is_account_admin":{"type":"boolean"},"is_entity_admin":{"type":"boolean"},"account_admin_override":{"type":"boolean","description":"Whether account owner/admin access grants management rights over this entity"},"can_manage_entity_users":{"type":"boolean"},"enforce_entity_admin_preservation":{"type":"boolean","description":"Whether final entity admin demotion/removal must be blocked for this actor"}},"required":["account_id","account_role","entity_id","entity_role","is_account_admin","is_entity_admin","account_admin_override","can_manage_entity_users","enforce_entity_admin_preservation"]},"GenerateUserTokenResponse":{"allOf":[{"$ref":"#/components/schemas/AccessToken"},{"type":"object","properties":{"entity_id":{"type":"string","description":"Entity ID the token is scoped to","example":"ent_xyz789"}},"required":["entity_id"]}],"description":"Access token for authentication"},"AccessToken":{"type":"object","properties":{"id":{"type":"string","maxLength":100},"user_id":{"type":"string","maxLength":36},"ttl":{"type":"number","default":31536000,"description":"Token time-to-live in seconds","example":31536000},"scope":{"type":["string","null"],"maxLength":50},"created_at":{"type":"string","format":"date-time"},"impersonator_user_id":{"type":["string","null"],"maxLength":36},"updated_at":{"type":"string","format":"date-time"}},"required":["id","user_id","ttl","created_at","updated_at"],"description":"Access token for authentication"},"EntityInvitationsList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EntityInvitation"}}},"required":["data"]},"EntityInvitation":{"type":"object","properties":{"id":{"type":"string","description":"Invitation ID","example":"einv_abc123"},"entity_id":{"type":"string","description":"Entity ID","example":"ent_xyz789"},"email":{"type":"string","description":"Invitee email","example":"newuser@example.com"},"role":{"type":"string","enum":["viewer","editor","admin"],"description":"User role on the entity","example":"editor"},"invited_by_user_id":{"type":"string","description":"ID of user who sent the invitation","example":"user_inviter123"},"expires_at":{"type":"string","format":"date-time","description":"When the invitation expires"},"accepted_at":{"type":["string","null"],"format":"date-time","description":"When the invitation was accepted (null if pending)"},"status":{"type":"string","enum":["pending","accepted","expired"],"description":"Current status of the invitation"},"created_at":{"type":"string","format":"date-time","description":"When the invitation was created"}},"required":["id","entity_id","email","role","invited_by_user_id","expires_at","accepted_at","status","created_at"]},"ResendInvitationResponse":{"type":"object","properties":{"message":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}},"required":["message","expires_at"]},"EntityInvitationPreview":{"type":"object","properties":{"email":{"type":"string","format":"email"},"entity_name":{"type":"string"},"existing_user":{"type":"boolean"},"role":{"type":"string","enum":["viewer","editor","admin"],"description":"User role on the entity","example":"editor"},"status":{"type":"string","enum":["pending","accepted","expired"]},"expires_at":{"type":"string","format":"date-time"}},"required":["email","entity_name","existing_user","role","status","expires_at"]},"AcceptInvitationResponse":{"type":"object","properties":{"message":{"type":"string"},"user_id":{"type":"string"},"entity_id":{"type":"string"},"access_token":{"type":"string","description":"Access token to use for authenticated requests"}},"required":["message","user_id","entity_id","access_token"]},"Entity":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"name":{"type":"string","maxLength":255},"address":{"type":["string","null"],"maxLength":500},"address_2":{"type":["string","null"],"maxLength":500},"post_code":{"type":["string","null"],"maxLength":20},"city":{"type":["string","null"],"maxLength":100},"state":{"type":["string","null"],"maxLength":100},"country":{"type":"string","maxLength":100},"country_code":{"type":"string","maxLength":2},"currency_code":{"type":["string","null"],"maxLength":3},"locale":{"type":"string","maxLength":20},"timezone":{"type":"string","maxLength":100,"description":"IANA timezone used for business calendar dates, including recurring document issue dates.","example":"Europe/Ljubljana"},"tax_number":{"type":["string","null"],"maxLength":50},"tax_number_2":{"type":["string","null"],"maxLength":50},"company_number":{"type":["string","null"],"maxLength":50},"phone":{"type":["string","null"],"maxLength":50},"email":{"type":["string","null"],"maxLength":255},"website":{"type":["string","null"],"maxLength":500},"fiscal_region_code":{"type":["string","null"],"maxLength":10},"starting_capital":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"account_id":{"type":"string","maxLength":36},"environment":{"type":"string","enum":["live","sandbox"],"description":"Entity environment"},"is_tax_subject":{"type":"boolean"},"is_enabled":{"type":"boolean","description":"Whether the entity is enabled. Disabled entities cannot create documents (invoices, estimates, etc.) but all data remains accessible and settings can be updated."},"settings":{"type":"object","properties":{"pdf_template":{"type":["string","null"],"enum":["modern","classic","condensed","minimal","fashion","timeless_modern_full_data",null],"description":"Default PDF template for document rendering. Defaults to 'modern' if not set.","example":"modern"},"number_formats":{"type":["object","null"],"properties":{"invoice":{"type":["string","null"]},"estimate":{"type":["string","null"]},"credit_note":{"type":["string","null"]},"advance_invoice":{"type":["string","null"]},"delivery_note":{"type":["string","null"]},"expense":{"type":["string","null"]}}},"unit_number_formats":{"type":["object","null"],"properties":{"invoice":{"type":["string","null"]},"estimate":{"type":["string","null"]},"credit_note":{"type":["string","null"]},"advance_invoice":{"type":["string","null"]},"delivery_note":{"type":["string","null"]}}},"number_sequence_starts":{"anyOf":[{"$ref":"#/components/schemas/NumberSequenceStarts"},{"type":"null"}]},"unit_number_sequence_starts":{"anyOf":[{"$ref":"#/components/schemas/UnitNumberSequenceStarts"},{"type":"null"}]},"primary_color":{"type":["string","null"],"pattern":"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"},"logo_scale_percent":{"type":["integer","null"],"minimum":30,"maximum":100,"description":"Scale the PDF logo size as a percentage of the template default size. 100 keeps the original size.","example":70},"has_logo":{"type":["boolean","null"]},"has_signature":{"type":["boolean","null"]},"default_invoice_due_days":{"type":["integer","null"],"exclusiveMinimum":0,"description":"Default number of days until invoice is due (from invoice date)","example":30},"default_estimate_valid_days":{"type":["integer","null"],"exclusiveMinimum":0,"description":"Default number of days until estimate expires (from estimate date)","example":30},"email":{"type":["string","null"],"format":"email","description":"Sender email address used for outgoing document and reminder emails. Falls back to the platform default sender when not set. Set to null to clear.","example":"billing@example.com"},"email_defaults":{"type":["object","null"],"properties":{"invoice_subject":{"type":["string","null"],"description":"Default subject line for invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_due_date}, {document_total}, {document_currency}","example":"Invoice {document_number} from {entity_name}"},"invoice_body":{"type":["string","null"],"description":"Default body text for invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_due_date}, {document_total}, {document_currency}","example":"Please find invoice {document_number} attached.\nDue date: {document_due_date}."},"estimate_subject":{"type":["string","null"],"description":"Default subject line for estimate emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_valid_until}, {document_total}, {document_currency}","example":"Estimate {document_number} from {entity_name}"},"estimate_body":{"type":["string","null"],"description":"Default body text for estimate emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_valid_until}, {document_total}, {document_currency}","example":"Please find estimate {document_number} attached.\nValid until: {document_valid_until}."},"credit_note_subject":{"type":["string","null"],"description":"Default subject line for credit note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Credit note {document_number} from {entity_name}"},"credit_note_body":{"type":["string","null"],"description":"Default body text for credit note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Please find credit note {document_number} attached."},"advance_invoice_subject":{"type":["string","null"],"description":"Default subject line for advance invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Advance invoice {document_number} from {entity_name}"},"advance_invoice_body":{"type":["string","null"],"description":"Default body text for advance invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Please find advance invoice {document_number} attached."},"delivery_note_subject":{"type":["string","null"],"description":"Default subject line for delivery note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Delivery note {document_number} from {entity_name}"},"delivery_note_body":{"type":["string","null"],"description":"Default body text for delivery note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Please find delivery note {document_number} attached."}}},"default_invoice_note":{"type":["string","null"],"description":"Default note for new invoices. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Payment due by {document_due_date}. Please reference invoice {document_number} when making payment."},"default_invoice_payment_terms":{"type":["string","null"],"description":"Default payment terms for new invoices. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Please remit payment using the bank details shown on the document."},"default_estimate_note":{"type":["string","null"],"description":"Default note for new estimates. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_valid_until}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"This estimate is valid until {document_valid_until}."},"default_estimate_payment_terms":{"type":["string","null"],"description":"Default payment terms for new estimates. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_valid_until}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Payment due upon acceptance."},"default_credit_note_note":{"type":["string","null"],"description":"Default note for new credit notes. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Credit note for invoice {document_number}."},"default_credit_note_payment_terms":{"type":["string","null"],"description":"Default payment terms for new credit notes. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Credit will be applied to your account."},"default_advance_invoice_note":{"type":["string","null"],"description":"Default note for new advance invoices. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Advance payment requested for {document_number}."},"default_delivery_note_note":{"type":["string","null"],"description":"Default note for new delivery notes. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Goods delivered under delivery note {document_number}."},"document_footer":{"type":["string","null"],"maxLength":500,"description":"Footer text for PDF documents. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"{entity_name} | Due Date: {document_due_date} | Invoice #{document_number}"},"default_document_signature":{"type":["string","null"],"description":"Default signature text for all new documents. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"{entity_name}"},"translations":{"anyOf":[{"$ref":"#/components/schemas/EntitySettingsTranslations"},{"type":"null"}],"description":"Translated default document-facing settings keyed by full supported locales. Used when new documents inherit default texts and when document defaults are rendered in an explicit non-default language."},"calculation":{"anyOf":[{"$ref":"#/components/schemas/CalculationSettings"},{"type":"null"}],"description":"Document calculation defaults. Controls whether newly calculated documents use the standard B2B net-first model or the B2C gross-discount model by default."},"slovenia":{"anyOf":[{"$ref":"#/components/schemas/SloveniaEntitySettings"},{"type":"null"}],"description":"Slovenia-specific tax profile used by yearly eDavki exports and future Slovenia-specific reporting flows."},"furs":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Whether FURS fiscalization is enabled for this entity","example":true},"default_skip_fiscalization":{"type":"boolean","default":false,"description":"Whether new FURS-capable documents should start with fiscalization skipped by default. Payment type rules still override this and require fiscalization for non-bank-transfer payments.","example":false},"numbering_strategy":{"type":"string","enum":["B","C"],"description":"Numbering strategy: B (device-level) or C (centralized). Optional - can be set per-premise.","example":"C"},"operator_tax_number":{"type":"string","description":"Operator tax number for this entity (used when creating invoices via API key)","example":"12345678"},"operator_label":{"type":"string","description":"Operator label/name for this entity","example":"Cash Register 1"},"foreign_operator":{"type":"boolean","description":"Whether the operator is a foreign legal entity","example":false},"environment":{"type":"string","enum":["test","production"],"description":"FURS environment override (test or production). When omitted, derived from entity environment.","example":"test"}},"description":"FURS (Slovenia) fiscalization settings. Certificate data is stored separately via the certificate upload endpoint."},"fina":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Whether CIS (FINA) fiscalization is enabled for this entity","example":true},"operator_oib":{"type":"string","minLength":11,"maxLength":11,"description":"OIB of the operator (11 digits). Used when creating invoices via API key.","example":"12345678901"},"operator_label":{"type":"string","description":"Operator label/name for this entity","example":"Cash Register 1"},"u_sust_pdv":{"type":"boolean","default":true,"description":"Whether the entity is in the PDV (VAT) system. Most businesses are.","example":true},"numbering_sequence":{"type":"string","enum":["N","P"],"default":"P","description":"Numbering sequence: P (per premise) or N (per device)","example":"P"},"unified_numbering":{"type":["boolean","null"],"description":"When enabled (default: true), all documents use the same FINA numbering sequence regardless of transaction type (domestic/non-domestic)","example":true},"certificate_expiry":{"type":"string","description":"Certificate expiry date (ISO 8601 format)","example":"2026-12-31T23:59:59.000Z"}},"description":"FINA (Croatia) CIS fiscalization settings. Required for Croatian B2C invoicing. Certificate data is stored separately via the certificate upload endpoint."},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtEntitySettings"},{"type":"null"}],"description":"Portugal operator defaults used for PT document creation when request-level or user-level PT operator data is not available."},"tax_rules":{"anyOf":[{"$ref":"#/components/schemas/TaxRules"},{"type":"null"}],"description":"Tax rules engine settings. Controls automatic tax behaviors based on entity location and transaction characteristics (VIES validation, reverse charge, export tax removal). Defaults are set automatically based on entity country. Set to null for non-EU entities."},"overdue_notifications":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Enable automatic overdue invoice notification emails to customers","example":true},"threshold_days":{"type":"array","items":{"type":"integer","exclusiveMinimum":0},"default":[7,14,30],"description":"Days overdue when notification emails are sent (exact day match). Email is triggered when any invoice hits these thresholds.","example":[7,14,30]},"email_subject":{"type":["string","null"],"deprecated":true,"description":"Deprecated legacy content field. Use settings.payment_reminders.email_subject for reminder email content. Automatic reminder scheduling remains configured under overdue_notifications.","example":"Payment reminder from {entity_name}"},"email_body":{"type":["string","null"],"deprecated":true,"description":"Deprecated legacy content field. Use settings.payment_reminders.email_body for reminder email content. Automatic reminder scheduling remains configured under overdue_notifications.","example":"Hello,\n\nThe invoices below are overdue. Please arrange payment of {total_amount} at your earliest convenience.\n\n{invoice_list}\n\n{payment_instructions}\n\nIf you have already paid, please disregard this reminder.\n\nBest regards,"}},"description":"Settings for automatic overdue invoice notification emails to customers"},"payment_reminders":{"type":["object","null"],"properties":{"email_subject":{"type":["string","null"],"description":"Default subject for manual and automatic payment reminder emails. Available variables: {customer_name}, {entity_name}, {overdue_count}","example":"Payment reminder from {entity_name}"},"email_body":{"type":["string","null"],"description":"Default body for manual and automatic payment reminder emails. Available variables: {customer_name}, {entity_name}, {invoice_list}, {payment_instructions}, {total_amount}, {entity_email}, {overdue_count}. Missing invoice list or payment instructions blocks are appended automatically.","example":"Hello,\n\nThe invoices below are overdue. Please arrange payment of {total_amount} at your earliest convenience.\n\n{invoice_list}\n\n{payment_instructions}\n\nIf you have already paid, please disregard this reminder.\n\nBest regards,"},"payment_instructions":{"type":["string","null"],"description":"Default payment instructions for payment reminder emails. Supports bank placeholders: {iban}, {bic}, {bank_name}, {account_number}, {routing_number}, {sort_code}","example":"Please remit payment to IBAN {iban}."}},"description":"Shared content defaults for manual and automatic payment reminder emails. Automatic reminder scheduling remains configured under overdue_notifications."},"upn_qr":{"anyOf":[{"$ref":"#/components/schemas/UpnQrSettings"},{"type":"null"}],"description":"UPN QR payment slip settings (Slovenia only). Displays payment QR code on invoices for easy bank transfers."},"epc_qr":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","description":"Whether EPC QR code is enabled on EUR invoices (SEPA countries)","example":true}},"required":["enabled"],"description":"EPC QR code settings (SEPA countries). Displays SEPA credit transfer QR code on EUR invoices for easy bank payment."},"hub3_qr":{"anyOf":[{"$ref":"#/components/schemas/Hub3QrSettings"},{"type":"null"}],"description":"Croatian HUB3 PDF417 payment barcode settings. Displays the barcode used by Croatian banking apps on EUR invoices."},"bank_accounts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/EntityBankAccount"},"description":"Bank accounts for receiving payments. The first account with is_default=true (or first in list) is used for new invoices."},"eslog_validation_enabled":{"type":["boolean","null"],"description":"Enable e-SLOG 2.0 validation for documents. Only applicable for Slovenian entities (country_code = 'SI'). When enabled, documents are validated against e-SLOG 2.0 requirements and can be exported as e-SLOG XML if valid.","example":true},"ujp_validation_with_eslog_enabled":{"type":["boolean","null"],"description":"When true for Slovenian entities, API/UI document create flows that enable e-SLOG also validate UJP package/envelope requirements for supported document types. Web may expose UJP download as a secondary e-SLOG dropdown action when current UJP validation is valid.","example":false},"xrechnung":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Enable German XRechnung XML validation by default and export actions for finalized German invoices and credit notes. Only applies to German entities whose country rules include e_invoicing. Final create/update calls only fail on validation errors when the request xrechnung.validation_required flag is true; XRechnung export always requires a current valid validation result.","example":true}},"description":"German XRechnung XML export settings. Separate from Peppol sending/onboarding settings and separate from document xrechnung validation state."},"zugferd":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Enable German ZUGFeRD/Factur-X validation by default and export actions for finalized German invoices and credit notes. Only applies to German entities whose country rules include e_invoicing. Final create/update calls only fail on validation errors when the request zugferd.validation_required flag is true; ZUGFeRD export always requires a current valid validation result.","example":true}},"description":"German ZUGFeRD/Factur-X PDF export settings. Separate from Peppol sending/onboarding settings and separate from document zugferd validation state."},"delivery_note_hide_prices":{"type":["boolean","null"],"description":"Default hide_prices setting for new delivery notes. When true, prices and totals are hidden (packing list mode).","example":false},"credit_note_negative_values":{"type":["boolean","null"],"description":"When true (default), credit note PDFs display line item quantities and totals as negative values while keeping prices positive. Zero quantities and totals stay unsigned. Set to false to show quantities and totals as positive.","example":true},"show_payment_amounts":{"type":["boolean","null"],"description":"When true, rendered document payment/refund sections show the payment amount next to each payment type. Defaults to false, which shows only the payment or refund type.","example":false},"receipt_note":{"type":["string","null"],"maxLength":500,"description":"Default note printed on thermal receipts."},"receipt_footer":{"type":["string","null"],"maxLength":500,"description":"Default footer text printed on thermal receipts (e.g. IBAN, thank-you message)."},"receipt_signature":{"type":["string","null"],"maxLength":200,"description":"Default signature / issuer label printed on thermal receipts."},"tax_clause_defaults":{"anyOf":[{"$ref":"#/components/schemas/TaxClauseDefaults"},{"type":"null"}],"description":"Default tax clauses per transaction type. Auto-applied to documents based on transaction type determination. Supports template variables: {entity_name}, {customer_name}, {document_number}, etc."},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/EInvoicingEntitySettings"},{"type":"null"}],"description":"E-invoicing settings for sending documents via the Peppol network. Requires verified entity enrollment before documents can be sent electronically."},"revenue_recognition":{"anyOf":[{"$ref":"#/components/schemas/RevenueRecognitionSettings"},{"type":"null"}],"description":"Deferred revenue and accrued revenue settings. When enabled, finalized eligible sales documents generate monthly recognition entries from their service periods."},"expense_recognition":{"anyOf":[{"$ref":"#/components/schemas/ExpenseRecognitionSettings"},{"type":"null"}],"description":"Expense recognition settings. Finalized expenses can generate monthly recognition entries from service periods."}},"description":"Entity settings"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"country_rules":{"$ref":"#/components/schemas/CountryRules"}},"required":["id","name","country","country_code","locale","account_id","environment","is_tax_subject","is_enabled","settings","created_at","updated_at","country_rules"],"description":"Legal entity (business, club, sole-proprietor, ...) on which invoices and other resources are created."},"NumberSequenceStarts":{"type":"object","properties":{"invoice":{"type":["integer","null"],"exclusiveMinimum":0},"estimate":{"type":["integer","null"],"exclusiveMinimum":0},"credit_note":{"type":["integer","null"],"exclusiveMinimum":0},"advance_invoice":{"type":["integer","null"],"exclusiveMinimum":0},"delivery_note":{"type":["integer","null"],"exclusiveMinimum":0}},"description":"Optional first sequence number to use for standard numbering per document type. Values may only move future numbering forward."},"UnitNumberSequenceStarts":{"type":"object","properties":{"invoice":{"type":["object","null"],"additionalProperties":{"type":["integer","null"],"exclusiveMinimum":0}},"estimate":{"type":["object","null"],"additionalProperties":{"type":["integer","null"],"exclusiveMinimum":0}},"credit_note":{"type":["object","null"],"additionalProperties":{"type":["integer","null"],"exclusiveMinimum":0}},"advance_invoice":{"type":["object","null"],"additionalProperties":{"type":["integer","null"],"exclusiveMinimum":0}},"delivery_note":{"type":["object","null"],"additionalProperties":{"type":["integer","null"],"exclusiveMinimum":0}}},"description":"Optional first sequence number to use for standard business-unit numbering per document type and business unit id. Values may only move future numbering forward."},"CalculationSettings":{"type":"object","properties":{"default_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Default document calculation mode. `b2b_standard` applies discounts before VAT on the net basis. `b2c_gross_discount` applies discounts to the gross payable amount and derives net/VAT afterward.","example":"b2b_standard"}}},"SloveniaEntitySettings":{"type":"object","properties":{"business_form":{"type":["string","null"],"enum":["sp","doo","dno","club",null],"description":"Stored Slovenian legal form for country-specific exports and reporting.","example":"sp"},"income_tax_regime":{"type":["string","null"],"enum":["normirani","dejanski",null],"description":"Stored Slovenian income tax regime for yearly reporting.","example":"normirani"},"vat_profile":{"type":["string","null"],"enum":["standard","special_vat_identified","non_vat_subject",null],"description":"Stored Slovenian VAT subject subtype.","example":"standard"},"tax_residency":{"type":["string","null"],"enum":["resident","non_resident",null],"description":"Stored Slovenian tax residency status.","example":"resident"},"yearly_reporting":{"anyOf":[{"$ref":"#/components/schemas/SloveniaYearlyReportingSettings"},{"type":"null"}],"description":"Slovenia-specific yearly reporting defaults and profile data."},"accounting_exports":{"anyOf":[{"$ref":"#/components/schemas/SloveniaAccountingExportsSettings"},{"type":"null"}],"description":"Slovenia-specific accounting export defaults and konto mappings."}}},"SloveniaYearlyReportingSettings":{"type":"object","properties":{"activity_codes":{"type":["array","null"],"items":{"type":"string","pattern":"^\\d{2}\\.\\d{3}$","description":"Slovenian SKD activity code used for yearly reporting.","example":"62.010"},"description":"Ordered Slovenian SKD activity codes used for yearly reporting.","example":["62.010","47.910"]},"registration_number":{"type":["string","null"],"maxLength":50,"description":"Optional registration number / branch registration used in yearly reporting.","example":"1234567"},"accounting_type":{"type":["string","null"],"enum":["records","single_entry","double_entry",null],"description":"Bookkeeping / records mode used in the yearly filing.","example":"records"},"normiranec_insurance_basis":{"type":["string","null"],"enum":["full_time_self_employed","other",null],"description":"Insurance basis used for normirani expense and tax rules.","example":"full_time_self_employed"},"default_withholding_tax_amount":{"type":["number","null"],"minimum":0,"description":"Persisted default for withholding tax manually entered during yearly review.","example":0},"default_foreign_tax_credit_amount":{"type":["number","null"],"minimum":0,"description":"Persisted default for foreign tax credit manually entered during yearly review.","example":0}}},"SloveniaAccountingExportsSettings":{"type":"object","properties":{"preferred_format":{"type":["string","null"],"enum":["vod_xml","vasco_xml","minimax_xml",null],"description":"Stored preferred export format for Slovenian accounting handoff.","example":"vod_xml"},"konto_mappings":{"anyOf":[{"$ref":"#/components/schemas/SloveniaAccountingKontoMappings"},{"type":"null"}],"description":"Stored semantic konto mappings shared by Slovenian accounting exports."}}},"SloveniaAccountingKontoMappings":{"type":"object","properties":{"receivables":{"type":["string","null"],"maxLength":8},"payables":{"type":["string","null"],"maxLength":8},"sales_vat_22":{"type":["string","null"],"maxLength":8},"sales_vat_95":{"type":["string","null"],"maxLength":8},"sales_vat_5":{"type":["string","null"],"maxLength":8},"purchase_vat_recoverable_22":{"type":["string","null"],"maxLength":8},"purchase_vat_recoverable_95":{"type":["string","null"],"maxLength":8},"purchase_vat_recoverable_5":{"type":["string","null"],"maxLength":8},"sales_revenue_22":{"type":["string","null"],"maxLength":8},"sales_revenue_95":{"type":["string","null"],"maxLength":8},"sales_revenue_5":{"type":["string","null"],"maxLength":8},"sales_revenue_exempt":{"type":["string","null"],"maxLength":8},"sales_revenue_eu_goods":{"type":["string","null"],"maxLength":8},"sales_revenue_eu_services":{"type":["string","null"],"maxLength":8},"sales_revenue_reverse_charge":{"type":["string","null"],"maxLength":8},"sales_revenue_third_country_goods":{"type":["string","null"],"maxLength":8},"sales_revenue_third_country_services":{"type":["string","null"],"maxLength":8},"purchase_expense_22":{"type":["string","null"],"maxLength":8},"purchase_expense_95":{"type":["string","null"],"maxLength":8},"purchase_expense_5":{"type":["string","null"],"maxLength":8},"purchase_expense_exempt":{"type":["string","null"],"maxLength":8},"purchase_expense_eu_goods":{"type":["string","null"],"maxLength":8},"purchase_expense_eu_services":{"type":["string","null"],"maxLength":8},"purchase_expense_reverse_charge":{"type":["string","null"],"maxLength":8},"purchase_expense_third_country_goods":{"type":["string","null"],"maxLength":8},"purchase_expense_third_country_services":{"type":["string","null"],"maxLength":8}}},"PtEntitySettings":{"type":"object","properties":{"operator_first_name":{"type":"string","minLength":1,"description":"Default PT operator first name for API key and headless document creation","example":"Joao"},"operator_last_name":{"type":"string","minLength":1,"description":"Default PT operator last name for API key and headless document creation","example":"Silva"},"operator_tax_number":{"type":"string","pattern":"^\\d{9}$","description":"Default PT operator tax number for API key and headless document creation","example":"123456789"}}},"TaxRules":{"type":"object","properties":{"eu":{"anyOf":[{"$ref":"#/components/schemas/EuTaxRules"},{"type":"null"}],"description":"EU tax rules settings. Only applicable for entities based in EU countries. Set to null or omit for non-EU entities."}},"description":"Tax rules engine settings. Controls automatic tax behaviors based on entity location and transaction characteristics. Set to null for non-EU entities."},"EuTaxRules":{"type":"object","properties":{"vies_validate_vat":{"type":"boolean","default":true,"description":"Validate EU VAT numbers against the VIES API. When enabled, customer VAT numbers are checked for validity before creating invoices. Validation results are cached on customer records. If VIES is unavailable, invoice creation continues with a warning.","example":true},"auto_reverse_charge":{"type":"boolean","default":false,"description":"Automatically apply 0% tax (reverse charge) for intra-EU B2B transactions. When enabled, taxes are removed and replaced with reverse charge note for valid VIES-validated cross-border B2B sales. Requires vies_validate_vat to be enabled for VAT validation.","example":false},"auto_remove_tax_export":{"type":"boolean","default":false,"description":"Automatically remove all taxes for exports to non-EU countries. When enabled, invoices to customers outside the EU will have all tax lines removed.","example":false},"require_gross_prices":{"type":"boolean","default":false,"description":"Require gross prices when reverse charge is applied. When enabled, creates a validation error if net prices are used with reverse charge transactions, since removing tax would change the invoice total.","example":false}},"description":"EU-specific tax rules for automatic VAT handling and cross-border transactions"},"UpnQrSettings":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether UPN QR payment slip is enabled on invoices (Slovenia only)","example":true},"display_mode":{"type":"string","enum":["qr_only","full_slip"],"default":"qr_only","description":"Display mode for UPN payment slip: 'qr_only' shows QR code inline after content, 'full_slip' shows complete payment slip at page bottom","example":"qr_only"},"purpose_code":{"type":"string","minLength":4,"maxLength":4,"pattern":"^[A-Z]{4}$","default":"OTHR","description":"4-letter purpose code for UPN payments (ISO 20022). Common values: OTHR (other), GDSV (goods/services), SALA (salary)","example":"OTHR"}},"required":["enabled"]},"Hub3QrSettings":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether Croatian HUB3 PDF417 payment barcode is enabled on invoices","example":true},"purpose_code":{"type":"string","minLength":4,"maxLength":4,"pattern":"^[A-Z]{4}$","default":"OTHR","description":"4-letter ISO 20022 purpose code for HUB3 payments","example":"OTHR"},"reference_model":{"type":"string","pattern":"^HR\\d{2}$","default":"HR00","description":"Croatian payment reference model, e.g. HR00 when no structured reference model is required","example":"HR00"}},"required":["enabled"]},"EInvoicingEntitySettings":{"type":"object","properties":{"enabled":{"type":"boolean","default":false,"description":"Whether e-invoicing is enabled for this entity. Requires entity enrollment to be completed before documents can be sent.","example":true},"auto_send":{"type":"boolean","default":false,"description":"Automatically send invoices via e-invoice after creation. Only works when entity enrollment is verified.","example":false}}},"RevenueRecognitionSettings":{"type":"object","properties":{"default_method":{"type":"string","enum":["off","service_period_daily"],"default":"off","description":"Entity default for generated revenue recognition entries. Individual document lines can opt out with method=immediate.","example":"service_period_daily"}},"additionalProperties":false},"ExpenseRecognitionSettings":{"type":"object","properties":{"default_method":{"type":"string","enum":["off","service_period_daily"],"default":"off","description":"Default expense recognition method. off keeps expenses immediate; service_period_daily spreads expense lines over their service period.","example":"service_period_daily"}},"additionalProperties":false},"CountryRules":{"type":"object","properties":{"max_taxes_per_item":{"type":"integer","minimum":1,"description":"Maximum number of taxes allowed per line item","example":1},"features":{"type":"array","items":{"type":"string"},"description":"Available country-specific features (availability only, not enabled status)","example":["furs","eslog"]}},"required":["max_taxes_per_item","features"],"description":"Country-specific rules derived from entity's country_code"},"EntityEmailSenderResponse":{"type":"object","properties":{"configured":{"anyOf":[{"$ref":"#/components/schemas/EmailSender"},{"type":"null"}]},"inherited":{"anyOf":[{"$ref":"#/components/schemas/EmailSender"},{"type":"null"}]},"effective":{"$ref":"#/components/schemas/EmailSenderEffective"}},"required":["configured","inherited","effective"]},"EmailSender":{"type":"object","properties":{"email":{"type":"string","format":"email"},"verification_status":{"type":"string","enum":["pending","verified","failed"]},"verified_at":{"type":["string","null"],"format":"date-time"},"domain":{"type":["string","null"]},"email_verification_status":{"type":"string","enum":["pending","verified","failed"]},"domain_verification_status":{"type":"string","enum":["pending","verified","failed"]},"domain_dkim_tokens":{"type":"array","items":{"type":"string"}},"last_checked_at":{"type":["string","null"],"format":"date-time"}},"required":["email","verification_status","verified_at","domain","email_verification_status","domain_verification_status","domain_dkim_tokens","last_checked_at"],"description":"Custom outbound From email verification state."},"EmailSenderEffective":{"type":"object","properties":{"source":{"type":"string","enum":["entity","white_label","default"]},"email":{"type":["string","null"],"format":"email"},"verified":{"type":"boolean"}},"required":["source","email","verified"],"description":"Resolved custom sender source used for delivery when verified."},"EmailSenderUpdateRequest":{"type":"object","properties":{"email":{"type":["string","null"],"format":"email"}},"required":["email"],"description":"Set a custom sender email, or clear it with null."},"PdfExportByDocumentIds":{"type":"object","properties":{"document_ids":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Specific document IDs to export. Types are inferred from ID prefixes.","example":["inv_clx1234567890","est_clx0987654321"]},"locale":{"type":["string","null"],"enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS",null],"description":"Override PDF formatting locale. When omitted or null, defaults to the entity locale.","example":"de-DE"},"language":{"type":["string","null"],"enum":["en","de","sl","it","fr","es","pt","nl","pl","hr","sv","fi","et","bg","cs","sk","nb","is",null],"description":"Override PDF label language. When omitted or null, defaults to the locale language, then entity locale.","example":"de"}},"required":["document_ids"]},"PdfExportByDateRange":{"type":"object","properties":{"types":{"type":"array","items":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice","delivery_note"],"description":"Document type to export","example":"invoice"},"minItems":1,"description":"Document types to export. Supports multiple types in a single export.","example":["invoice"]},"date_from":{"type":["string","null"],"description":"Start date filter (ISO 8601 date). Date range cannot exceed 1 year. Omit or use null to skip.","example":"2024-01-01"},"date_to":{"type":["string","null"],"description":"End date filter (ISO 8601 date). Date range cannot exceed 1 year. Omit or use null to skip.","example":"2024-12-31"},"locale":{"type":["string","null"],"enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS",null],"description":"Override PDF formatting locale. When omitted or null, defaults to the entity locale.","example":"de-DE"},"language":{"type":["string","null"],"enum":["en","de","sl","it","fr","es","pt","nl","pl","hr","sv","fi","et","bg","cs","sk","nb","is",null],"description":"Override PDF label language. When omitted or null, defaults to the locale language, then entity locale.","example":"de"}},"required":["types"]},"EslogExportByDocumentIds":{"type":"object","properties":{"document_ids":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Specific document IDs to export as e-SLOG XML. Types are inferred from ID prefixes.","example":["inv_clx1234567890","est_clx0987654321"]}},"required":["document_ids"]},"EslogExportByDateRange":{"type":"object","properties":{"types":{"type":"array","items":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice"],"description":"Document type to export as e-SLOG XML","example":"invoice"},"minItems":1,"description":"Document types to export as e-SLOG XML. Supports multiple types in a single export.","example":["invoice","credit_note"]},"date_from":{"type":["string","null"],"description":"Start date filter (ISO 8601 date). Date range cannot exceed 1 year. Omit or use null to skip.","example":"2024-01-01"},"date_to":{"type":["string","null"],"description":"End date filter (ISO 8601 date). Date range cannot exceed 1 year. Omit or use null to skip.","example":"2024-12-31"}},"required":["types"]},"FinancialCategoryResponse":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"entity_id":{"type":"string","maxLength":36},"name":{"type":"string","maxLength":200},"color":{"type":["string","null"],"description":"Optional UI color for the category.","example":"#2563eb"},"sort_order":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"archived_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","entity_id","name","sort_order","created_at","updated_at"],"description":"Entity-scoped financial category shared across revenue and future expense reporting."},"RevenueByCategoryResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RevenueByCategoryRow"}},"total":{"type":"number"},"currency_code":{"type":"string"},"date_from":{"type":"string"},"date_to":{"type":"string"}},"required":["data","total","currency_code","date_from","date_to"]},"RevenueByCategoryRow":{"type":"object","properties":{"financial_category_id":{"type":["string","null"]},"name":{"type":"string"},"color":{"type":["string","null"]},"amount":{"type":"number"},"percentage":{"type":"number"},"currency_code":{"type":"string"}},"required":["financial_category_id","name","color","amount","percentage","currency_code"]},"DocumentItemFinancialCategoryAssignments":{"type":"array","items":{"$ref":"#/components/schemas/DocumentItemFinancialCategoryAssignment"}},"DocumentItemFinancialCategoryAssignment":{"type":"object","properties":{"document_item_id":{"type":"string"},"financial_category_id":{"type":["string","null"]}},"required":["document_item_id","financial_category_id"]},"BusinessUnitResponse":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"entity_id":{"type":"string","maxLength":36},"name":{"type":"string","maxLength":255},"address":{"type":["string","null"],"maxLength":500},"address_2":{"type":["string","null"],"maxLength":500},"post_code":{"type":["string","null"],"maxLength":20},"city":{"type":["string","null"],"maxLength":100},"state":{"type":["string","null"],"maxLength":100},"country":{"type":["string","null"],"maxLength":100},"country_code":{"type":["string","null"],"maxLength":2},"email":{"type":["string","null"],"maxLength":255},"phone":{"type":["string","null"],"maxLength":50},"website":{"type":["string","null"],"maxLength":500},"settings":{"$ref":"#/components/schemas/BusinessUnitSettings"},"numbering_index":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"logo_file_id":{"type":["string","null"],"maxLength":36},"signature_file_id":{"type":["string","null"],"maxLength":36},"is_active":{"type":"boolean"},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","entity_id","name","settings","numbering_index","is_active","created_at","updated_at"],"description":"Business-unit resource scoped to an entity."},"ItemResponse":{"allOf":[{"$ref":"#/components/schemas/Item"},{"type":"object","properties":{}}],"description":"Item or Service provided to customers by the Entity"},"Item":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"name":{"type":"string","maxLength":500},"description":{"type":["string","null"],"maxLength":2000},"classification":{"type":["string","null"],"enum":["product","service","advance",null],"description":"Item classification used for Portugal SAF-T product typing.","example":"service"},"price":{"type":"number","description":"Per-unit net price (before tax). Always stores net price.","example":100},"gross_price":{"type":["number","null"],"description":"Per-unit gross price (includes tax). Only present if user originally sent gross price.","example":122},"price_with_tax":{"type":"number","description":"Per-unit price including tax. Stored for fast B2C/POS display regardless of input mode.","example":122},"unit":{"type":["string","null"],"description":"Default display unit for document lines created from this saved item.","example":"hours"},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemEInvoicingData"},{"type":"null"}],"description":"Default line-level e-invoicing options for document lines created from this saved item."},"tax_ids":{"type":"array","items":{"type":"string","maxLength":36}},"total_tax":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"entity_id":{"type":"string","maxLength":36},"financial_category_id":{"type":["string","null"],"description":"Default financial category for this item. In v1 only income categories can be assigned.","example":"fcat_abc123"},"metadata":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"translations":{"$ref":"#/components/schemas/DocumentItemTranslations"},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","price","price_with_tax","tax_ids","total_tax","entity_id","metadata","translations","created_at","updated_at"],"description":"Product or service item"},"Payment":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"invoice_id":{"type":["string","null"],"maxLength":36},"credit_note_id":{"type":["string","null"],"maxLength":36},"advance_invoice_id":{"type":["string","null"],"maxLength":36},"expense_id":{"type":["string","null"],"maxLength":36},"applied_to_expense_id":{"type":["string","null"],"maxLength":36},"amount":{"type":"number","description":"Payment amount in the linked document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents.","example":29.9},"currency_code":{"type":"string","maxLength":3},"amount_converted":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"type":{"type":"string","enum":["cash","bank_transfer","card","check","paypal","coupon","other","credit_note","advance"],"description":"Payment type/method"},"date":{"type":"string","format":"date-time","description":"Date the payment was received (ISO 8601 datetime at midnight UTC)"},"tag":{"type":["string","null"],"maxLength":100},"reference":{"type":["string","null"],"maxLength":100},"note":{"type":["string","null"],"maxLength":500},"entity_id":{"type":"string","maxLength":36},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"Invoice":{"type":["object","null"],"properties":{"id":{"type":"string","maxLength":36},"number":{"type":"string","maxLength":100}},"required":["id","number"],"description":"Related invoice"},"CreditNote":{"type":["object","null"],"properties":{"id":{"type":"string","maxLength":36},"number":{"type":"string","maxLength":100}},"required":["id","number"],"description":"Related credit note"},"AdvanceInvoice":{"type":["object","null"],"properties":{"id":{"type":"string","maxLength":36},"number":{"type":"string","maxLength":100}},"required":["id","number"],"description":"Related advance invoice"},"Expense":{"type":["object","null"],"properties":{"id":{"type":"string","maxLength":36},"type":{"$ref":"#/components/schemas/ExpenseType"},"supplier_document_number":{"type":["string","null"],"maxLength":255},"date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"total_with_tax":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327}},"required":["id","type"],"description":"Related expense"},"AppliedToExpense":{"type":["object","null"],"properties":{"id":{"type":"string","maxLength":36},"type":{"$ref":"#/components/schemas/ExpenseType"},"supplier_document_number":{"type":["string","null"],"maxLength":255},"date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"total_with_tax":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327}},"required":["id","type"],"description":"Related expense"}},"required":["id","amount","currency_code","amount_converted","type","date","entity_id","created_at","updated_at"],"description":"Payment record for an outgoing document or expense"},"ExpenseType":{"type":"string","enum":["invoice","credit_note","advance_invoice"],"description":"Expense document type. V1 accepts `invoice` only; AP credit notes and advance invoices are reserved for a later version."},"TaxResponse":{"allOf":[{"$ref":"#/components/schemas/Tax"},{"type":"object","properties":{}}],"description":"Tax with one or more rates, each with a valid_from date for historical rate tracking"},"Tax":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"name":{"type":"string","maxLength":100},"tax_rates":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number","minimum":0,"maximum":100},"valid_from":{"type":"string","format":"date-time"}},"required":["rate","valid_from"]},"description":"Tax rate history"},"is_default":{"type":"boolean","description":"Whether this is the default tax for new documents. Only one tax per entity can be default.","example":true},"classification":{"type":["string","null"],"description":"Classification for API tax lookups (e.g., \"standard\", \"reduced\", \"zero\"). Unique per entity. Can be used instead of rate when creating documents.","example":"standard"},"pt_exemption_code":{"type":["string","null"],"description":"Portugal exemption code for 0% / exempt / non-subject taxes.","example":"M13"},"pt_exemption_reason":{"type":["string","null"],"description":"Portugal exemption reason associated with pt_exemption_code.","example":"Regime da margem de lucro - Bens em segunda mao"},"entity_id":{"type":"string","maxLength":36},"metadata":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","tax_rates","is_default","entity_id","metadata","created_at","updated_at"],"description":"Tax definition with rate history"},"FileMetadata":{"allOf":[{"$ref":"#/components/schemas/FileMetadataBase"},{"type":"object","properties":{}}],"description":"File metadata record with upload information"},"FileMetadataBase":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"entity_id":{"type":"string","maxLength":36},"business_unit_id":{"type":["string","null"],"maxLength":36},"invoice_id":{"type":["string","null"],"maxLength":36},"estimate_id":{"type":["string","null"],"maxLength":36},"credit_note_id":{"type":["string","null"],"maxLength":36},"advance_invoice_id":{"type":["string","null"],"maxLength":36},"expense_id":{"type":["string","null"],"maxLength":36},"category":{"type":"string","maxLength":20},"url":{"type":"string","maxLength":500},"secureUrl":{"type":"string","maxLength":500,"deprecated":true,"description":"Deprecated compatibility alias for secure_url. Use secure_url for new integrations."},"publicId":{"type":"string","maxLength":200,"deprecated":true,"description":"Deprecated compatibility alias for public_id. Use public_id for new integrations."},"format":{"type":"string","maxLength":20},"width":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"height":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"bytes":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"filename":{"type":["string","null"],"maxLength":255},"mime_type":{"type":"string","maxLength":100},"metadata":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"cache_key":{"type":["string","null"],"maxLength":255},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"secure_url":{"type":"string","maxLength":500,"description":"Secure HTTPS URL of the uploaded file. Use this snake_case field for new integrations."},"public_id":{"type":"string","maxLength":200,"description":"Storage object key for future reference or deletion. Use this snake_case field for new integrations."}},"required":["id","entity_id","category","url","secureUrl","publicId","format","bytes","mime_type","metadata","created_at","updated_at","secure_url","public_id"],"description":"File metadata record with upload information"},"LoginResponse":{"allOf":[{"$ref":"#/components/schemas/AccessToken"},{"type":"object","properties":{"user":{"$ref":"#/components/schemas/User"},"redirect_origin":{"type":["string","null"]}},"required":["user"]}],"description":"Access token for authentication"},"User":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"email":{"type":"string","maxLength":255},"name":{"type":["string","null"],"maxLength":255},"email_verified":{"type":"boolean"},"account_id":{"type":["string","null"],"maxLength":36},"settings":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"metadata":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","email","email_verified","settings","metadata","created_at","updated_at"]},"CreatedUser":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"email":{"type":"string","maxLength":255},"name":{"type":["string","null"]},"email_verified":{"type":"boolean"},"account_id":{"type":["string","null"],"maxLength":36},"settings":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","email","name","email_verified","settings","created_at","updated_at"],"description":"User account with access to one or more Entities. Users can authenticate via Bearer token and manage resources within their authorized entities and accounts."},"PasswordResetMessage":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"AccountsListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountInfo"}}},"required":["data"]},"AccountInfo":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member"]}},"required":["id","name","role"]},"AccountDeletionRequest":{"type":"object","properties":{"requested_at":{"type":"string","format":"date-time"},"retention_notice":{"type":"string"}},"required":["requested_at","retention_notice"]},"Customer":{"allOf":[{"$ref":"#/components/schemas/CustomerBase"},{"type":"object","properties":{}}],"description":"Customer of the Entity"},"CustomerBase":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"name":{"type":"string","maxLength":255},"address":{"type":["string","null"],"maxLength":500},"address_2":{"type":["string","null"],"maxLength":500},"post_code":{"type":["string","null"],"maxLength":20},"city":{"type":["string","null"],"maxLength":100},"state":{"type":["string","null"],"maxLength":100},"country":{"type":["string","null"],"maxLength":100},"country_code":{"type":["string","null"],"maxLength":2},"tax_number":{"type":["string","null"],"maxLength":50},"company_number":{"type":["string","null"],"maxLength":50},"peppol_id":{"type":["string","null"],"maxLength":50},"peppol_scheme_id":{"type":["string","null"],"maxLength":10},"bank_accounts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/EntityBankAccount"}},"email":{"type":["string","null"],"maxLength":255},"contact_type":{"type":"string","maxLength":20},"is_tax_subject":{"type":"boolean"},"is_end_consumer":{"type":"boolean"},"entity_id":{"type":"string","maxLength":36},"vies":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpCustomerData"},{"type":"null"}]},"metadata":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","contact_type","is_tax_subject","is_end_consumer","entity_id","ujp","metadata","created_at","updated_at"],"description":"Customer information"},"Expense":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"number":{"type":"string","maxLength":100},"entity_id":{"type":"string","maxLength":36},"supplier_id":{"type":["string","null"],"maxLength":36},"type":{"$ref":"#/components/schemas/ExpenseType"},"is_draft":{"type":"boolean"},"voided_at":{"type":["string","null"],"format":"date-time"},"deleted_at":{"type":["string","null"],"format":"date-time"},"supplier":{"anyOf":[{"$ref":"#/components/schemas/ExpenseSupplier"},{"type":"null"}]},"supplier_document_number":{"type":["string","null"],"maxLength":255},"date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"date_received":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"currency_code":{"type":["string","null"],"maxLength":3},"transaction_type":{"type":["string","null"],"maxLength":50},"reference":{"type":["string","null"],"maxLength":100},"note":{"type":["string","null"],"maxLength":2000},"summary_classification":{"anyOf":[{"$ref":"#/components/schemas/ExpenseSummaryClassification"},{"type":"null"}]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/ExpenseSummaryTax"}},"total":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"total_with_tax":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"total_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"total_with_tax_converted":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"total_discount":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"creation_source":{"type":"string","description":"Internal origin of the create request. `standard` means the normal create endpoint calculated the totals. `custom` means the document was created through the `/expenses/custom` endpoint (this is also what legacy-migrated expenses use). `ocr` means the expense was created from an OCR-extracted document.","example":"standard"},"total_paid":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_due":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"paid_in_full":{"type":"boolean"},"date_year":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"exchange_rate":{"anyOf":[{"$ref":"#/components/schemas/ExchangeRate"},{"type":"null"}]},"metadata":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ExpenseItem"}},"attachment_count":{"type":"integer","minimum":0},"has_attachment":{"type":"boolean"}},"required":["id","number","entity_id","type","is_draft","supplier","taxes","total_discount","creation_source","total_paid","total_due","paid_in_full","date_year","metadata","created_at","updated_at","items","attachment_count","has_attachment"],"description":"Expense"},"ExpenseSupplier":{"type":"object","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"],"maxLength":255},"address":{"type":["string","null"]},"address_2":{"type":["string","null"]},"post_code":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]},"country_code":{"type":["string","null"],"maxLength":2},"tax_number":{"type":["string","null"]},"company_number":{"type":["string","null"]},"phone":{"type":["string","null"]},"peppol_id":{"type":["string","null"]},"bank_accounts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/EntityBankAccount"}},"is_tax_subject":{"type":["boolean","null"]}}},"ExpenseSummaryClassification":{"type":"string","enum":["product","service"]},"ExpenseSummaryTax":{"type":"object","properties":{"rate":{"type":["number","null"]},"tax_id":{"type":["string","null"]},"base":{"type":"number"},"amount":{"type":"number"},"base_converted":{"type":["number","null"]},"amount_converted":{"type":["number","null"]},"reverse_charge":{"type":["boolean","null"],"description":"Whether the tax is self-assessed/reverse charged and should not be added to gross total."},"is_deductible":{"type":["boolean","null"],"description":"Compatibility flag derived from deductible_percentage when supplied. Without a percentage, true resolves to 100 and false resolves to 0."},"deductible_percentage":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Percentage of input tax that is deductible for AP bookkeeping, from 0 through 100."}},"required":["rate","base","amount"]},"ExpenseItem":{"type":"object","properties":{"type":{"type":["string","null"],"enum":["separator",null]},"item_id":{"type":["string","null"]},"name":{"type":"string","minLength":1},"description":{"type":["string","null"]},"quantity":{"type":["number","null"]},"unit":{"type":["string","null"]},"classification":{"type":["string","null"],"enum":["product","service","advance",null]},"financial_category_id":{"type":["string","null"]},"expense_recognition":{"anyOf":[{"$ref":"#/components/schemas/ExpenseItemRecognition"},{"type":"null"}]},"price":{"type":["number","null"]},"gross_price":{"type":["number","null"]},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/LineDiscount"},"default":[]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentItemTax"},"default":[]},"total":{"type":["number","null"]},"total_with_tax":{"type":["number","null"]},"total_tax":{"type":"number"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentItemTranslations"},{"description":"Translated user-authored line-item content keyed by full supported locales. Base item fields remain the default-language source of truth."}]},{"type":"null"}],"description":"Optional or null translated user-authored line-item content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"name":{"de-DE":"Beratungsleistungen"},"description":{"de-DE":"Retainer fuer Maerz"}}}},"required":["name","quantity","classification","price","total","total_with_tax","total_tax"],"additionalProperties":false},"ExpenseItemRecognition":{"type":"object","properties":{"method":{"type":["string","null"],"enum":["immediate","service_period_daily",null]},"date_from":{"type":["string","null"],"format":"date"},"date_to":{"type":["string","null"],"format":"date"}},"additionalProperties":false},"ExpenseDuplicateConflictError":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"conflicting_expense_id":{"type":["string","null"],"description":"ID of the active expense using the same supplier document number."}},"required":["conflicting_expense_id"]}],"description":"Standard error response format used across all API endpoints. Includes a machine-readable error code and human-readable message."},"CreateExpenseItem":{"type":"object","properties":{"type":{"type":["string","null"],"enum":["separator",null],"description":"Item type. Omit or null for a regular line item, or use `separator` for a visual section header."},"item_id":{"type":["string","null"],"description":"ID of a catalog item to prefill from. Catalog values are used as defaults; supplied fields override them.","example":"item_abc123"},"save_item":{"type":["boolean","null"],"description":"Whether to save or match this line to the catalog. Defaults to best-effort true for regular line items."},"name":{"type":["string","null"],"minLength":1},"description":{"type":["string","null"]},"quantity":{"type":["number","null"]},"unit":{"type":["string","null"]},"classification":{"type":["string","null"],"enum":["product","service","advance",null]},"financial_category_id":{"type":["string","null"]},"expense_recognition":{"anyOf":[{"$ref":"#/components/schemas/ExpenseItemRecognition"},{"type":"null"}],"description":"Optional line-level recognition override. immediate uses the expense date; service_period_daily spreads the line over date_from/date_to or the expense service period."},"price":{"type":["number","null"]},"gross_price":{"type":["number","null"]},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/LineDiscount"},"default":[]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentItemTax"},"default":[]},"total":{"type":["number","null"]},"total_with_tax":{"type":["number","null"]},"total_tax":{"type":["number","null"]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentItemTranslations"},{"description":"Translated user-authored line-item content keyed by full supported locales. Base item fields remain the default-language source of truth."}]},{"type":"null"}],"description":"Optional or null translated user-authored line-item content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"name":{"de-DE":"Beratungsleistungen"},"description":{"de-DE":"Retainer fuer Maerz"}}}},"additionalProperties":false},"CustomExpenseWrite":{"type":"object","properties":{"type":{"type":"string","enum":["invoice"],"default":"invoice","description":"Expense document type. Optional — defaults to `invoice` (the only value supported in V1; AP credit notes and advance invoices are reserved for a later version)."},"is_draft":{"type":["boolean","null"],"default":false,"description":"Whether to save the expense as an incomplete draft. Defaults to false."},"supplier_id":{"type":["string","null"]},"supplier":{"anyOf":[{"$ref":"#/components/schemas/ExpenseSupplier"},{"type":"null"}]},"save_supplier":{"type":["boolean","null"],"description":"Whether to save supplier data to the contact directory. When `supplier` is provided, this defaults to true. On update, `save_supplier: true` without a `supplier` object re-applies the expense's stored supplier snapshot to the linked contact."},"supplier_document_number":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"The supplier's own invoice number as printed on their document. Used for duplicate awareness (unique per supplier for active expenses) and accounting exports.","example":"AP-2024-0417"},"date":{"type":["string","null"],"format":"date"},"date_received":{"type":["string","null"],"format":"date"},"date_due":{"type":["string","null"],"format":"date"},"date_service":{"type":["string","null"],"format":"date"},"date_service_to":{"type":["string","null"],"format":"date"},"currency_code":{"type":["string","null"],"minLength":3,"maxLength":3},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export",null]},"reference":{"type":["string","null"],"maxLength":100},"note":{"type":["string","null"],"maxLength":2000},"items":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CustomExpenseItem"}},"taxes":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ExpenseSummaryTax"}},"total":{"type":["number","null"]},"total_with_tax":{"type":["number","null"]},"total_discount":{"type":["number","null"]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"payments":{"type":["array","null"],"items":{"type":"object","properties":{"amount":{"type":["number","null"],"exclusiveMinimum":0,"description":"Payment amount in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. If omitted, the document total (`total_with_tax`) is used."},"date":{"type":["string","null"],"description":"Payment date in YYYY-MM-DD format. Defaults to today.","example":"2024-01-15"},"tag":{"type":["string","null"]},"reference":{"type":["string","null"]},"note":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"type":{"type":"string","enum":["cash","bank_transfer","card","check","paypal","coupon","other","advance"]}},"required":["type"],"additionalProperties":false},"description":"Optional payments to record with the expense. If amounts are omitted, the remaining total_with_tax is split equally. Automatically updates expense payment status."},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode validation override for `/custom` endpoints. When omitted, totals are accepted as provided and no calculation validation runs. When provided, Space Invoices validates the supplied totals against the selected mode before creating the document.","example":"b2b_standard"},"exchange_rate":{"anyOf":[{"$ref":"#/components/schemas/ExchangeRate"},{"type":"null"}]},"summary_classification":{"anyOf":[{"$ref":"#/components/schemas/ExpenseSummaryClassification"},{"type":"null"}]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"additionalProperties":false},"CustomExpenseItem":{"type":"object","properties":{"type":{"type":["string","null"],"enum":["separator",null],"description":"Item type. Omit or null for a regular line item, or use `separator` for a visual section header."},"item_id":{"type":["string","null"],"description":"ID of a catalog item to prefill from. Catalog values are used as defaults; supplied fields override them.","example":"item_abc123"},"save_item":{"type":["boolean","null"],"description":"Whether to save or match this line to the catalog. Defaults to best-effort true for regular line items."},"name":{"type":["string","null"],"minLength":1},"description":{"type":["string","null"]},"quantity":{"type":["number","null"]},"unit":{"type":["string","null"]},"classification":{"type":["string","null"],"enum":["product","service","advance",null]},"financial_category_id":{"type":["string","null"]},"expense_recognition":{"anyOf":[{"$ref":"#/components/schemas/ExpenseItemRecognition"},{"type":"null"}],"description":"Optional line-level recognition override. immediate uses the expense date; service_period_daily spreads the line over date_from/date_to or the expense service period."},"price":{"type":["number","null"]},"gross_price":{"type":["number","null"]},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/LineDiscount"},"default":[]},"taxes":{"type":"array","items":{"$ref":"#/components/schemas/DocumentItemTax"},"default":[]},"total":{"type":["number","null"]},"total_with_tax":{"type":["number","null"]},"total_tax":{"type":["number","null"]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentItemTranslations"},{"description":"Translated user-authored line-item content keyed by full supported locales. Base item fields remain the default-language source of truth."}]},{"type":"null"}],"description":"Optional or null translated user-authored line-item content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"name":{"de-DE":"Beratungsleistungen"},"description":{"de-DE":"Retainer fuer Maerz"}}}},"additionalProperties":false},"ExpenseCategoryReportResponse":{"type":"object","properties":{"basis":{"type":"string","enum":["recognized","deferred"]},"group_by":{"type":"string","enum":["financial_category"]},"calculation_mode":{"type":"string","enum":["recognition_entries","document_date_fallback","mixed"]},"periods":{"type":"array","items":{"$ref":"#/components/schemas/ExpenseCategoryReportPeriod"}},"series":{"type":"array","items":{"$ref":"#/components/schemas/ExpenseCategoryReportSeries"}},"totals":{"type":"array","items":{"type":"number"}},"total":{"type":"number"},"currency_code":{"type":"string"},"date_from":{"type":"string"},"date_to":{"type":"string"}},"required":["basis","group_by","calculation_mode","periods","series","totals","total","currency_code","date_from","date_to"]},"ExpenseCategoryReportPeriod":{"type":"object","properties":{"period":{"type":"string"},"date_from":{"type":"string"},"date_to":{"type":"string"}},"required":["period","date_from","date_to"]},"ExpenseCategoryReportSeries":{"type":"object","properties":{"key":{"type":"string"},"financial_category_id":{"type":["string","null"]},"name":{"type":"string"},"color":{"type":["string","null"]},"values":{"type":"array","items":{"type":"number"}},"total":{"type":"number"}},"required":["key","financial_category_id","name","color","values","total"]},"ExpenseRecognitionSettingsResponse":{"type":"object","properties":{"default_method":{"type":"string","enum":["off","service_period_daily"],"default":"off","description":"Default expense recognition method. off keeps expenses immediate; service_period_daily spreads expense lines over their service period.","example":"service_period_daily"}},"additionalProperties":false},"UpdateExpenseRecognitionSettings":{"type":"object","properties":{"default_method":{"type":["string","null"],"enum":["off","service_period_daily",null],"default":"off","description":"Default expense recognition method. off keeps expenses immediate; service_period_daily spreads expense lines over their service period.","example":"service_period_daily"}},"additionalProperties":false},"ExpenseRecognitionBackfillResponse":{"type":"object","properties":{"processed_expenses":{"type":"integer","minimum":0},"generated_entries":{"type":"integer","minimum":0},"dry_run":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["processed_expenses","generated_entries","dry_run","next_cursor"]},"ExpenseRecognitionBackfill":{"type":"object","properties":{"date_from":{"type":["string","null"],"format":"date"},"date_to":{"type":["string","null"],"format":"date"},"dry_run":{"type":"boolean","default":false},"cursor":{"type":["string","null"],"description":"Exclusive expense ID cursor returned by the previous batch."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":100}},"additionalProperties":false},"ExpenseRecognitionCreateResponse":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/ExpenseRecognitionJob"},"expense_id":{"type":"string"},"file_metadata_id":{"type":"string"},"status":{"$ref":"#/components/schemas/ExpenseRecognitionJobStatus"}},"required":["job","expense_id","file_metadata_id","status"]},"ExpenseRecognitionJob":{"type":"object","properties":{"id":{"type":"string","description":"Recognition job ID","example":"erj_6595a27b5d35015c3ef0c3fd"},"entity_id":{"type":"string","description":"Entity that owns the job"},"expense_id":{"type":"string","description":"Draft expense created for this recognition"},"file_metadata_id":{"type":"string","description":"Source attachment file metadata ID"},"status":{"$ref":"#/components/schemas/ExpenseRecognitionJobStatus"},"provider":{"type":["string","null"],"description":"OCR provider (set after processing)"},"model":{"type":["string","null"],"description":"OCR model identifier"},"parser_version":{"type":["string","null"],"description":"Parser contract version"},"attempts":{"type":"integer","minimum":0},"max_attempts":{"type":"integer","exclusiveMinimum":0},"pages_processed":{"type":["integer","null"],"minimum":0},"page_count":{"type":["integer","null"],"minimum":0},"warnings":{"type":["array","null"],"items":{"type":"object","properties":{"code":{"type":"string","enum":["missing_required_field","invalid_date","invalid_currency","invalid_amount","totals_mismatch","tax_mismatch","importer_supplier_ambiguity","low_confidence","unsupported_value","partial_payment_evidence","payment_status_uncertain","reconciliation_incomplete","unsupported_document_type"]},"field":{"type":["string","null"]},"message":{"type":"string"}},"required":["code","field","message"]}},"provenance":{"anyOf":[{"type":"object","properties":{"provider":{"type":"string","enum":["mistral"]},"model":{"type":"string"},"parser_version":{"type":"string"},"pages_processed":{"type":["integer","null"],"minimum":0},"doc_size_bytes":{"type":["integer","null"],"minimum":0},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"page":{"type":["integer","null"],"exclusiveMinimum":0},"confidence":{"type":["number","null"],"minimum":0,"maximum":1},"source":{"type":["string","null"],"enum":["annotation","ocr","derived","importing_entity",null]},"note":{"type":["string","null"]}},"required":["field","page","confidence","source","note"]}}},"required":["provider","model","parser_version","pages_processed","doc_size_bytes","fields"]},{"type":"null"}]},"reconciliation":{"anyOf":[{"type":"object","properties":{"is_reconciled":{"type":"boolean"},"expected_total":{"type":["number","null"]},"expected_total_with_tax":{"type":["number","null"]},"expected_tax":{"type":["number","null"]},"reported_total":{"type":["number","null"]},"reported_total_with_tax":{"type":["number","null"]},"reported_tax":{"type":["number","null"]},"differences":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"expected":{"type":["number","null"]},"reported":{"type":["number","null"]},"delta":{"type":["number","null"]}},"required":["field","expected","reported","delta"]}}},"required":["is_reconciled","expected_total","expected_total_with_tax","expected_tax","reported_total","reported_total_with_tax","reported_tax","differences"]},{"type":"null"}]},"payment_suggestion":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["paid","unpaid","unknown"]},"amount":{"type":["number","null"]},"date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"method":{"type":["string","null"]},"evidence":{"type":"array","items":{"type":"string"}},"confidence":{"type":["number","null"],"minimum":0,"maximum":1},"is_partial":{"type":"boolean"}},"required":["status","amount","date","method","evidence","confidence","is_partial"]},{"type":"null"}]},"extracted_draft":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["invoice"]},"supplier":{"type":["object","null"],"properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"]},"address":{"type":["string","null"]},"address_2":{"type":["string","null"]},"post_code":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]},"country_code":{"type":["string","null"],"maxLength":2,"pattern":"^[A-Za-z]{2}$"},"tax_number":{"type":["string","null"]},"company_number":{"type":["string","null"]},"phone":{"type":["string","null"]},"peppol_id":{"type":["string","null"]},"bank_accounts":{"type":["array","null"],"items":{"type":"object","properties":{"iban":{"type":["string","null"]},"bic":{"type":["string","null"]},"bank_name":{"type":["string","null"]},"account_number":{"type":["string","null"]},"currency_code":{"type":["string","null"]}}}},"is_tax_subject":{"type":["boolean","null"]}},"required":["name","email","address","address_2","post_code","city","state","country","country_code","tax_number","company_number","phone","peppol_id","bank_accounts","is_tax_subject"]},"supplier_document_number":{"type":["string","null"]},"date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"date_received":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"date_due":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"date_service":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"date_service_to":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"currency_code":{"type":["string","null"],"minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$"},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export",null]},"reference":{"type":["string","null"]},"note":{"type":["string","null"]},"items":{"type":["array","null"],"items":{"type":"object","properties":{"name":{"type":["string","null"]},"description":{"type":["string","null"]},"quantity":{"type":["number","null"]},"unit":{"type":["string","null"]},"classification":{"type":["string","null"],"enum":["product","service","advance",null]},"price":{"type":["number","null"]},"gross_price":{"type":["number","null"]},"discounts":{"type":["array","null"],"items":{"type":"object","properties":{"value":{"type":["number","null"]},"type":{"type":["string","null"],"enum":["percent","amount",null]}},"required":["value","type"]}},"taxes":{"type":["array","null"],"items":{"type":"object","properties":{"rate":{"type":["number","null"]},"amount":{"type":["number","null"]},"reverse_charge":{"type":["boolean","null"]},"is_deductible":{"type":["boolean","null"]},"deductible_percentage":{"type":["number","null"],"minimum":0,"maximum":100}},"required":["rate","amount","reverse_charge","is_deductible","deductible_percentage"]}},"total":{"type":["number","null"]},"total_with_tax":{"type":["number","null"]},"total_tax":{"type":["number","null"]}},"required":["name","description","quantity","unit","classification","price","gross_price","discounts","taxes","total","total_with_tax","total_tax"]}},"taxes":{"type":["array","null"],"items":{"type":"object","properties":{"rate":{"type":["number","null"]},"base":{"type":["number","null"]},"amount":{"type":["number","null"]},"reverse_charge":{"type":["boolean","null"]},"is_deductible":{"type":["boolean","null"]},"deductible_percentage":{"type":["number","null"],"minimum":0,"maximum":100}},"required":["rate","base","amount","reverse_charge","is_deductible","deductible_percentage"]}},"total":{"type":["number","null"]},"total_with_tax":{"type":["number","null"]},"total_discount":{"type":["number","null"]},"summary_classification":{"type":["string","null"],"enum":["product","service",null]}},"required":["type","supplier","supplier_document_number","date","date_received","date_due","date_service","date_service_to","currency_code","transaction_type","reference","note","items","taxes","total","total_with_tax","total_discount","summary_classification"]},{"type":"null"}]},"error_code":{"type":["string","null"],"description":"Safe machine-readable failure code"},"error_message":{"type":["string","null"],"description":"Safe human-readable failure message"},"request_id":{"type":["string","null"],"description":"X-Request-Id used at admission, when provided"},"source_filename":{"type":["string","null"]},"source_mime_type":{"type":"string"},"source_bytes":{"type":"integer","minimum":0},"source_content_sha256":{"type":"string","description":"SHA-256 of the uploaded source bytes"},"simulation_mode":{"type":["string","null"],"enum":["sandbox_demo",null],"description":"Present when recognition used a deterministic sandbox demo instead of the uploaded document"},"source_replaced":{"type":"boolean","description":"Whether the uploaded source was discarded and replaced with a sandbox demo document"},"expense_updated_at_snapshot":{"type":"string","format":"date-time"},"queued_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","entity_id","expense_id","file_metadata_id","status","attempts","max_attempts","source_mime_type","source_bytes","source_content_sha256","simulation_mode","source_replaced","expense_updated_at_snapshot","queued_at","created_at","updated_at"]},"ExpenseRecognitionJobStatus":{"type":"string","enum":["queued","processing","ready_for_review","needs_attention","failed"]},"ExpenseRecognitionLookupResponse":{"type":"object","properties":{"job":{"anyOf":[{"$ref":"#/components/schemas/ExpenseRecognitionJob"},{"type":"null"}]}},"required":["job"]},"ShareableId":{"type":"object","properties":{"shareable_id":{"type":"string","description":"Unique shareable token for public document access"}},"required":["shareable_id"],"description":"Response containing a shareable ID token"},"WebhookWithSecret":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"entity_id":{"type":"string","maxLength":36},"url":{"type":"string","maxLength":2048},"description":{"type":["string","null"],"maxLength":500},"secret":{"type":"string","maxLength":64},"events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.updated","invoice.sent","invoice.paid","invoice.overdue","invoice.cancelled","invoice.deleted","invoice.restored","invoice.voided","invoice.finalized","customer.created","customer.updated","customer.deleted","customer.restored","customer.permanently_deleted","payment.received","payment.failed","payment.deleted","payment.restored","payment.permanently_deleted","estimate.created","estimate.sent","estimate.accepted","estimate.rejected","estimate.deleted","estimate.restored","credit_note.created","credit_note.issued","credit_note.voided","credit_note.deleted","credit_note.restored","advance_invoice.created","advance_invoice.paid","advance_invoice.applied","advance_invoice.voided","advance_invoice.deleted","advance_invoice.restored","item.created","item.updated","item.deleted","item.restored","item.permanently_deleted","tax.created","tax.updated","tax.deleted","tax.restored","tax.permanently_deleted","recurring_invoice.created","recurring_invoice.updated","recurring_invoice.deleted","recurring_invoice.restored","recurring_invoice.permanently_deleted","recurring_invoice.paused","recurring_invoice.resumed","recurring_invoice.invoice_generated","recurring_invoice.generation_failed","recurring_invoice.completed","stripe_app.connected","stripe_app.disconnected","stripe_app.settings_updated","order.created","order.updated","order.deleted","order.restored","order.permanently_deleted","order.processed","order.cancelled","order.failed","order_integration.created","order_integration.updated","order_integration.deleted","delivery_note.created","delivery_note.sent","delivery_note.cancelled","delivery_note.voided","delivery_note.deleted","delivery_note.restored","expense.created","expense.updated","expense.finalized","expense.voided","expense.deleted","e_invoicing.submission.created","e_invoicing.submission.delivered","e_invoicing.submission.failed","e_invoicing.enrollment.verified","e_invoicing.enrollment.rejected","e_invoicing.supplier.onboarded","e_invoicing.supplier.rejected"]}},"active":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","entity_id","url","secret","events","active","created_at","updated_at"],"description":"Webhook endpoint with full secret visible"},"WebhookResponse":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"entity_id":{"type":"string","maxLength":36},"url":{"type":"string","maxLength":2048},"description":{"type":["string","null"],"maxLength":500},"events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.updated","invoice.sent","invoice.paid","invoice.overdue","invoice.cancelled","invoice.deleted","invoice.restored","invoice.voided","invoice.finalized","customer.created","customer.updated","customer.deleted","customer.restored","customer.permanently_deleted","payment.received","payment.failed","payment.deleted","payment.restored","payment.permanently_deleted","estimate.created","estimate.sent","estimate.accepted","estimate.rejected","estimate.deleted","estimate.restored","credit_note.created","credit_note.issued","credit_note.voided","credit_note.deleted","credit_note.restored","advance_invoice.created","advance_invoice.paid","advance_invoice.applied","advance_invoice.voided","advance_invoice.deleted","advance_invoice.restored","item.created","item.updated","item.deleted","item.restored","item.permanently_deleted","tax.created","tax.updated","tax.deleted","tax.restored","tax.permanently_deleted","recurring_invoice.created","recurring_invoice.updated","recurring_invoice.deleted","recurring_invoice.restored","recurring_invoice.permanently_deleted","recurring_invoice.paused","recurring_invoice.resumed","recurring_invoice.invoice_generated","recurring_invoice.generation_failed","recurring_invoice.completed","stripe_app.connected","stripe_app.disconnected","stripe_app.settings_updated","order.created","order.updated","order.deleted","order.restored","order.permanently_deleted","order.processed","order.cancelled","order.failed","order_integration.created","order_integration.updated","order_integration.deleted","delivery_note.created","delivery_note.sent","delivery_note.cancelled","delivery_note.voided","delivery_note.deleted","delivery_note.restored","expense.created","expense.updated","expense.finalized","expense.voided","expense.deleted","e_invoicing.submission.created","e_invoicing.submission.delivered","e_invoicing.submission.failed","e_invoicing.enrollment.verified","e_invoicing.enrollment.rejected","e_invoicing.supplier.onboarded","e_invoicing.supplier.rejected"]}},"active":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"Masked secret (only shown on create and rotate)","example":"whsec_****...****"}},"required":["id","entity_id","url","events","active","created_at","updated_at","secret"],"description":"Webhook endpoint (secret masked)"},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"webhook_id":{"type":"string","maxLength":36},"entity_id":{"type":"string","maxLength":36},"event_type":{"type":"string","maxLength":100},"status":{"type":"string","enum":["pending","success","failed"]},"request_body":{"type":"object","additionalProperties":{}},"response_status":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"response_body":{"type":["string","null"],"maxLength":10000},"error_message":{"type":["string","null"],"maxLength":2000},"attempt":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"max_attempts":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"next_retry_at":{"type":["string","null"],"format":"date-time"},"duration_ms":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}},"required":["id","webhook_id","entity_id","event_type","status","request_body","attempt","max_attempts","created_at"],"description":"Webhook delivery attempt record"},"AccountWebhookWithSecret":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"account_id":{"type":"string","maxLength":36},"url":{"type":"string","maxLength":2048},"description":{"type":["string","null"],"maxLength":500},"secret":{"type":"string","maxLength":64},"events":{"type":"array","items":{"type":"string","enum":["white_label_subscription.subscribed","white_label_subscription.upgraded","white_label_subscription.downgrade_scheduled","white_label_subscription.downgraded","white_label_subscription.cancellation_scheduled","white_label_subscription.cancelled","white_label_subscription.renewed","white_label_subscription.expired","white_label_subscription.payment_failed"]}},"active":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","account_id","url","secret","events","active","created_at","updated_at"],"description":"Account webhook endpoint with full secret visible"},"AccountWebhookResponse":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"account_id":{"type":"string","maxLength":36},"url":{"type":"string","maxLength":2048},"description":{"type":["string","null"],"maxLength":500},"events":{"type":"array","items":{"type":"string","enum":["white_label_subscription.subscribed","white_label_subscription.upgraded","white_label_subscription.downgrade_scheduled","white_label_subscription.downgraded","white_label_subscription.cancellation_scheduled","white_label_subscription.cancelled","white_label_subscription.renewed","white_label_subscription.expired","white_label_subscription.payment_failed"]}},"active":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"default":{}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"Masked secret (only shown on create and rotate)","example":"whsec_****...****"}},"required":["id","account_id","url","events","active","created_at","updated_at","secret"],"description":"Account webhook endpoint (secret masked)"},"AccountWebhookDelivery":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"account_webhook_id":{"type":"string","maxLength":36},"account_id":{"type":"string","maxLength":36},"entity_id":{"type":["string","null"],"maxLength":36},"event_type":{"type":"string","maxLength":100},"status":{"type":"string","enum":["pending","success","failed"]},"request_body":{"type":"object","additionalProperties":{}},"response_status":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"response_body":{"type":["string","null"],"maxLength":10000},"error_message":{"type":["string","null"],"maxLength":2000},"attempt":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"max_attempts":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"next_retry_at":{"type":["string","null"],"format":"date-time"},"duration_ms":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}},"required":["id","account_webhook_id","account_id","event_type","status","request_body","attempt","max_attempts","created_at"],"description":"Account webhook delivery attempt record"},"FursBusinessPremise":{"type":"object","properties":{"id":{"type":"string"},"entity_id":{"type":"string"},"business_premise_name":{"type":"string"},"type":{"type":"string"},"real_estate":{"anyOf":[{"$ref":"#/components/schemas/RealEstatePremise"},{"type":"null"}]},"movable_premise":{"anyOf":[{"$ref":"#/components/schemas/MovablePremise"},{"type":"null"}]},"is_active":{"type":"boolean"},"starting_number":{"type":["integer","null"]},"can_update_starting_number":{"type":"boolean"},"registered_at":{"type":"string","format":"date-time"},"closed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"Devices":{"type":"array","items":{"$ref":"#/components/schemas/FursElectronicDevice"}}},"required":["id","entity_id","business_premise_name","type","real_estate","movable_premise","is_active","starting_number","registered_at","closed_at","created_at","updated_at"]},"RealEstatePremise":{"type":"object","properties":{"cadastral_number":{"type":"string"},"building_number":{"type":["string","null"]},"building_section":{"type":["string","null"]},"community":{"type":"string"},"street":{"type":["string","null"]},"house_number":{"type":["string","null"]},"house_number_additional":{"type":["string","null"]},"city":{"type":["string","null"]},"postal_code":{"type":["string","null"]}},"required":["cadastral_number","building_number","building_section","community","street","house_number","house_number_additional","city","postal_code"]},"MovablePremise":{"type":"object","properties":{"type":{"type":"string"}},"required":["type"]},"FursElectronicDevice":{"type":"object","properties":{"id":{"type":"string"},"premise_id":{"type":"string"},"electronic_device_name":{"type":"string"},"is_active":{"type":"boolean"},"starting_number":{"type":["integer","null"]},"can_update_starting_number":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","premise_id","electronic_device_name","is_active","starting_number","created_at","updated_at"]},"FursPremiseSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Operation success status","example":true},"message":{"type":"string","description":"Success message","example":"Business premise registered successfully"},"business_premise_name":{"type":"string","description":"Registered business premise name","example":"P1"},"environment":{"type":"string","enum":["test","production"],"description":"FURS environment used","example":"production"}},"required":["success","message","business_premise_name","environment"]},"ElectronicDeviceSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Operation success status","example":true},"message":{"type":"string","description":"Success message","example":"Electronic device registered successfully"},"device_name":{"type":"string","description":"Name of the registered electronic device","example":"DEVICE1"}},"required":["success","message","device_name"]},"FinaBusinessPremise":{"type":"object","properties":{"id":{"type":"string"},"entity_id":{"type":"string"},"business_premise_name":{"type":"string"},"type":{"type":"string"},"real_estate":{"anyOf":[{"$ref":"#/components/schemas/FinaRealEstatePremise"},{"type":"null"}]},"movable_premise":{"anyOf":[{"$ref":"#/components/schemas/FinaMovablePremise"},{"type":"null"}]},"is_active":{"type":"boolean"},"starting_number":{"type":["integer","null"]},"can_update_starting_number":{"type":"boolean"},"registered_at":{"type":["string","null"],"format":"date-time"},"closed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"Devices":{"type":"array","items":{"$ref":"#/components/schemas/FinaElectronicDevice"}}},"required":["id","entity_id","business_premise_name","type","real_estate","movable_premise","is_active","starting_number","registered_at","closed_at","created_at","updated_at"]},"FinaRealEstatePremise":{"type":"object","properties":{"cadastral_municipality":{"type":"string"},"land_registry_number":{"type":"string"},"building_number":{"type":["string","null"]},"sub_building_number":{"type":["string","null"]},"street":{"type":["string","null"]},"house_number":{"type":["string","null"]},"house_number_additional":{"type":["string","null"]},"settlement":{"type":["string","null"]},"city":{"type":["string","null"]},"postal_code":{"type":["string","null"]}},"required":["cadastral_municipality","land_registry_number","building_number","sub_building_number","street","house_number","house_number_additional","settlement","city","postal_code"]},"FinaMovablePremise":{"type":"object","properties":{"type":{"type":"string"}},"required":["type"]},"FinaElectronicDevice":{"type":"object","properties":{"id":{"type":"string"},"premise_id":{"type":"string"},"electronic_device_name":{"type":"string"},"is_active":{"type":"boolean"},"starting_number":{"type":["integer","null"]},"can_update_starting_number":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","premise_id","electronic_device_name","is_active","starting_number","created_at","updated_at"]},"FinaPremiseSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Operation success status","example":true},"message":{"type":"string","description":"Success message","example":"Business premise created successfully"},"business_premise_name":{"type":"string","description":"Business premise name","example":"PP1"}},"required":["success","message","business_premise_name"]},"FinaElectronicDeviceSuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Operation success status","example":true},"message":{"type":"string","description":"Success message","example":"Electronic device registered successfully"},"electronic_device_name":{"type":"string","description":"Name of the registered electronic device","example":"1"}},"required":["success","message","electronic_device_name"]},"PtAtcudSeries":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"entity_id":{"type":"string","maxLength":36},"document_type":{"type":"string","enum":["invoice","advance_invoice","credit_note","estimate"],"description":"Portugal fiscal document type tracked for ATCUD series numbering.","example":"invoice"},"series_code":{"type":"string","minLength":1,"maxLength":35,"description":"AT-communicated series code used in the PT document number.","example":"FT 2026/A"},"validation_code":{"type":"string","minLength":1,"maxLength":32,"description":"Validation code assigned by AT for the communicated series.","example":"AB12CD34EF"},"first_number":{"type":"string","minLength":1,"maxLength":100,"description":"Legacy/legal first document number registered for this ATCUD series.","example":"FT FT2026A/00001"},"start_date":{"type":"string","format":"date","description":"First date for which the communicated series is valid.","example":"2026-01-01"},"is_manual":{"type":"boolean","description":"Whether this series is reserved for manually issued PT documents.","example":false},"initial_sequence":{"type":"integer","minimum":1,"description":"Initial PT legal sequence number for this series.","example":1}},"required":["id","entity_id","document_type","series_code","validation_code","first_number","start_date","is_manual","initial_sequence"],"description":"Portugal ATCUD series registration metadata."},"TransactionTypeCheckResponse":{"type":"object","properties":{"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c",null],"description":"Determined transaction type based on geography and tax status. 3w_b2b/3w_b2c = third-world (non-EU) B2B/B2C.","example":"intra_eu_b2b"},"reverse_charge_applies":{"type":"boolean","description":"Whether reverse charge should be applied (0% tax with reverse charge note)","example":true},"issuer_country_code":{"type":["string","null"],"minLength":2,"maxLength":2,"description":"Resolved issuer country code","example":"SI"},"customer_country_code":{"type":["string","null"],"minLength":2,"maxLength":2,"description":"Resolved customer country code","example":"DE"},"vies_valid":{"type":["boolean","null"],"description":"VIES validation result (true if tax number is valid, null if not checked)","example":true},"warning":{"type":["string","null"],"description":"Warning message if VIES validation was unavailable or tax number was invalid","example":null},"is_tax_subject":{"type":"boolean","description":"False when issuer is not a tax subject (transaction treated as B2C)","example":true}},"required":["transaction_type","reverse_charge_applies","issuer_country_code","customer_country_code","vies_valid","warning"]},"TransactionTypeCheckRequest":{"type":"object","properties":{"issuer":{"type":"object","properties":{"country":{"type":"string","description":"Country name (e.g., 'Germany', 'Deutschland', 'Slovenija'). Automatically resolved to country_code.","example":"Slovenia"},"country_code":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code. If provided, takes precedence over country name.","example":"SI"},"is_tax_subject":{"type":"boolean","default":true,"description":"Whether the issuer is a tax subject. Set false for small businesses or tax-exempt organizations.","example":true}},"description":"Issuer (seller) information"},"customer":{"type":"object","properties":{"country":{"type":"string","description":"Country name (e.g., 'Germany', 'Deutschland'). Automatically resolved to country_code.","example":"Germany"},"country_code":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code. If provided, takes precedence over country name.","example":"DE"},"tax_number":{"type":"string","description":"Customer tax number (with or without country prefix)","example":"DE123456789"},"is_end_consumer":{"type":"boolean","description":"Whether the customer is an end consumer (B2C override). When true, forces B2C classification for non-EU transactions even if customer has a tax number. For intra-EU, VIES validation takes precedence.","example":false}},"description":"Customer (buyer) information"}},"required":["issuer","customer"]},"EslogValidationResponse":{"type":"object","properties":{"document_id":{"type":"string","description":"Document ID"},"document_type":{"type":"string","description":"Document type"},"eslog":{"allOf":[{"$ref":"#/components/schemas/EslogData"},{"description":"e-SLOG validation result"}]}},"required":["document_id","document_type","eslog"]},"EInvoicingSettingsResponse":{"type":"object","properties":{"enabled":{"type":"boolean"},"auto_send":{"type":"boolean"},"default_scheme_id":{"type":"string"},"enrollment":{"$ref":"#/components/schemas/EInvoicingEnrollment"}},"required":["enabled","auto_send"],"description":"Current e-invoicing settings and enrollment state for the entity"},"EInvoicingEnrollment":{"type":"object","properties":{"id":{"type":["string","null"]},"entity_id":{"type":["string","null"]},"environment":{"type":["string","null"],"enum":["sandbox","live",null]},"state":{"$ref":"#/components/schemas/EInvoicingEnrollmentState"},"sending_allowed":{"type":"boolean"},"missing_fields":{"type":"array","items":{"type":"string"},"default":[]},"verification_url":{"type":["string","null"],"format":"uri"},"peppol_registered":{"type":["boolean","null"]},"peppol_id":{"type":["string","null"]},"peppol_scheme_id":{"type":["string","null"]},"provider_error":{"type":["string","null"]},"verified_at":{"type":["string","null"],"format":"date-time"},"last_synced_at":{"type":["string","null"],"format":"date-time"}},"required":["state","sending_allowed"],"description":"Entity enrollment status for Peppol sending"},"EInvoicingEnrollmentState":{"type":"string","enum":["not_enabled","missing_entity_data","enrollment_pending","verification_required","verification_in_progress","verified","reverification_required","rejected","provider_error"]},"UpdateEInvoicingSettingsRequest":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable or disable e-invoicing for this entity","example":true},"auto_send":{"type":"boolean","description":"Automatically send supported outgoing documents when e-invoicing is active","example":false},"default_scheme_id":{"type":"string","maxLength":10,"description":"Deprecated default Peppol participant scheme ID retained for client compatibility","example":"0009","deprecated":true}},"additionalProperties":false,"description":"Update e-invoicing settings for the entity"},"EInvoicingSupplier":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"entity_id":{"type":"string","maxLength":36},"environment":{"type":"string","maxLength":20},"status":{"type":"string","maxLength":50},"reject_reason":{"type":["string","null"]},"verification_url":{"type":["string","null"]},"last_synced_at":{"type":["string","null"],"format":"date-time"},"peppol_registered":{"type":["boolean","null"]},"peppol_participant_id":{"type":["string","null"],"maxLength":255},"peppol_scheme_id":{"type":["string","null"],"maxLength":10},"company_name":{"type":"string","maxLength":255},"vat_number":{"type":["string","null"],"maxLength":50},"company_number":{"type":["string","null"],"maxLength":50},"iban":{"type":["string","null"],"maxLength":50},"address":{"type":["string","null"],"maxLength":500},"city":{"type":["string","null"],"maxLength":100},"post_code":{"type":["string","null"],"maxLength":20},"country_code":{"type":"string","maxLength":2},"contact_email":{"type":["string","null"],"maxLength":255},"contact_phone":{"type":["string","null"],"maxLength":50},"kyc_id_document_url":{"type":["string","null"]},"kyc_business_register_url":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{},"default":{}},"onboarded_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","entity_id","environment","status","company_name","country_code","created_at","updated_at"],"description":"Deprecated supplier enrollment response retained for client compatibility"},"RegisterEInvoicingSupplierRequest":{"type":"object","properties":{"company_name":{"type":"string","minLength":1,"maxLength":255},"vat_number":{"type":"string","maxLength":50},"company_number":{"type":"string","maxLength":50},"iban":{"type":"string","maxLength":50},"address":{"type":"string","maxLength":500},"city":{"type":"string","maxLength":100},"post_code":{"type":"string","maxLength":20},"country_code":{"type":"string","minLength":2,"maxLength":2},"contact_email":{"type":"string","maxLength":255,"format":"email"},"contact_phone":{"type":"string","maxLength":50}},"required":["company_name","country_code"],"additionalProperties":false,"description":"Deprecated supplier enrollment request retained for client compatibility"},"UpdateEInvoicingSupplierRequest":{"type":"object","properties":{"company_name":{"type":"string","minLength":1,"maxLength":255},"vat_number":{"type":"string","maxLength":50},"company_number":{"type":"string","maxLength":50},"iban":{"type":"string","maxLength":50},"address":{"type":"string","maxLength":500},"city":{"type":"string","maxLength":100},"post_code":{"type":"string","maxLength":20},"country_code":{"type":"string","minLength":2,"maxLength":2},"contact_email":{"type":"string","maxLength":255,"format":"email"},"contact_phone":{"type":"string","maxLength":50}},"additionalProperties":false,"description":"Deprecated supplier enrollment update retained for client compatibility"},"EInvoicingRecipientCheckResponse":{"type":"object","properties":{"peppol_id":{"type":"string"},"scheme_id":{"type":"string"},"peppol_address":{"type":"string"},"registered":{"type":"boolean"},"name":{"type":["string","null"]},"document_type":{"type":["string","null"],"enum":["invoice","credit_note",null]},"document_supported":{"type":["boolean","null"]}},"required":["peppol_id","scheme_id","peppol_address","registered"],"description":"Recipient Peppol registration and optional document support result"},"CheckEInvoicingRecipientRequest":{"type":"object","properties":{"peppol_id":{"type":"string","minLength":1,"description":"Recipient Peppol identifier. May be a plain value or a full scheme:value address.","example":"0009:98765432109876"},"scheme_id":{"type":"string","minLength":1,"maxLength":10,"description":"Peppol scheme ID. Required when peppol_id is not provided as scheme:value.","example":"0009"},"document_type":{"type":"string","enum":["invoice","credit_note"],"description":"Optional document type support check","example":"invoice"}},"required":["peppol_id"],"additionalProperties":false,"description":"Check a recipient's Peppol registration and optional document type support"},"EInvoicingCustomerSearchResult":{"type":"object","properties":{"peppol_id":{"type":"string"},"scheme_id":{"type":"string"},"name":{"type":"string"},"country_code":{"type":"string"},"registered":{"type":"boolean"}},"required":["peppol_id","scheme_id","registered"],"description":"Deprecated recipient lookup result retained for client compatibility"},"EInvoicingCustomerSearchRequest":{"type":"object","properties":{"peppol_id":{"type":"string","minLength":1},"scheme_id":{"type":"string","minLength":1,"maxLength":10}},"required":["peppol_id","scheme_id"],"additionalProperties":false,"description":"Deprecated recipient lookup request retained for client compatibility"},"EInvoicingSubmission":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"entity_id":{"type":"string","maxLength":36},"supplier_id":{"type":"string","maxLength":36},"environment":{"type":"string","maxLength":20},"document_id":{"type":"string","maxLength":36},"document_type":{"type":"string","maxLength":20},"transmission_id":{"type":["string","null"],"maxLength":255},"recipient_peppol_id":{"type":["string","null"],"maxLength":255},"recipient_scheme_id":{"type":["string","null"],"maxLength":10},"recipient_name":{"type":["string","null"],"maxLength":255},"status":{"type":"string","maxLength":50},"error_message":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{},"default":{}},"submitted_at":{"type":["string","null"],"format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","entity_id","supplier_id","environment","document_id","document_type","status","created_at","updated_at"],"description":"E-invoice submission status"},"SendEInvoiceRequest":{"type":"object","properties":{"recipient_peppol_id":{"type":"string","minLength":1,"description":"Override recipient Peppol identifier. May be a plain value or a full scheme:value address. Omit to use the document customer.","example":"0009:98765432109876"},"recipient_scheme_id":{"type":"string","minLength":1,"maxLength":10,"description":"Override recipient scheme ID. Omit to use the document customer.","example":"0009"},"recipient_name":{"type":"string","minLength":1,"maxLength":255,"description":"Override recipient display name. Omit to use the document customer name.","example":"Client Corp SARL"}},"additionalProperties":false,"description":"Send an invoice or credit note over Peppol. Omit recipient fields to use the document customer."},"EInvoicingSubmissionDetail":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"entity_id":{"type":"string","maxLength":36},"supplier_id":{"type":"string","maxLength":36},"environment":{"type":"string","maxLength":20},"document_id":{"type":"string","maxLength":36},"document_type":{"type":"string","maxLength":20},"transmission_id":{"type":["string","null"],"maxLength":255},"recipient_peppol_id":{"type":["string","null"],"maxLength":255},"recipient_scheme_id":{"type":["string","null"],"maxLength":10},"recipient_name":{"type":["string","null"],"maxLength":255},"status":{"type":"string","maxLength":50},"error_message":{"type":["string","null"]},"ubl_xml":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{},"default":{}},"submitted_at":{"type":["string","null"],"format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","entity_id","supplier_id","environment","document_id","document_type","status","created_at","updated_at"],"description":"E-invoice submission detail including generated UBL XML"},"CompanyRegistrySearchResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CompanyRegistryResult"}}},"required":["data"]},"CompanyRegistryResult":{"type":"object","properties":{"id":{"type":"string"},"country_code":{"type":"string","minLength":2,"maxLength":2},"registration_number":{"type":"string"},"tax_number":{"type":["string","null"]},"name":{"type":"string"},"address":{"type":["string","null"]},"post_code":{"type":["string","null"]},"city":{"type":["string","null"]},"legal_form":{"type":["string","null"]},"bank_accounts":{"type":"array","items":{"$ref":"#/components/schemas/CompanyBankAccount"}},"status":{"type":"string"}},"required":["id","country_code","registration_number","tax_number","name","address","post_code","city","legal_form","bank_accounts","status"],"description":"Company from public registry for autocomplete"},"CompanyBankAccount":{"type":"object","properties":{"iban":{"type":"string","description":"IBAN or bank account number"},"bank":{"type":"string","description":"Bank name or code"},"is_active":{"type":"boolean","description":"Whether this account is currently active"}},"required":["iban"]},"SupportedCountriesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2}}},"required":["data"],"description":"List of country codes with registry data available"},"ExchangeRateLookup":{"type":"object","properties":{"rate":{"type":"number","exclusiveMinimum":0,"description":"Exchange rate: 1 from = rate to"},"source":{"type":["string","null"],"description":"Rate source identifier (e.g. 'auto' or 'manual'), or null when unavailable"},"date":{"type":"string","format":"date-time","description":"Date the rate applies to (ISO datetime)"},"from_currency":{"type":"string","minLength":3,"maxLength":3,"description":"Source currency"},"to_currency":{"type":"string","minLength":3,"maxLength":3,"description":"Quote currency"},"available":{"type":"boolean","description":"Whether a rate was found for the pair/date"}},"required":["rate","source","date","from_currency","to_currency","available"]},"TaxRateEstimate":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"country_code":{"type":"string","maxLength":2},"state":{"type":"string","maxLength":2},"zip_code":{"type":"string","maxLength":10},"tax_region_name":{"type":"string","maxLength":255},"estimated_combined_rate":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"state_rate":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"county_rate":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"city_rate":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"special_rate":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"risk_level":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"source":{"type":"string","maxLength":50},"source_month":{"type":"string","maxLength":7},"imported_at":{"type":"string","format":"date-time"}},"required":["id","country_code","state","zip_code","tax_region_name","estimated_combined_rate","state_rate","county_rate","city_rate","special_rate","risk_level","source","source_month","imported_at"],"description":"Imported ZIP-level tax-rate estimate. This is informational and must be verified before use."},"RecurringInvoice":{"allOf":[{"$ref":"#/components/schemas/RecurringInvoiceBase"},{"type":"object","properties":{}}],"description":"Recurring invoice schedule"},"RecurringInvoiceBase":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"entity_id":{"type":"string","maxLength":36},"document_id":{"type":"string","maxLength":36},"name":{"type":"string","maxLength":255},"frequency":{"type":"string","enum":["daily","weekly","monthly","yearly"],"description":"Recurrence frequency"},"interval":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"day_of_week":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"day_of_month":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"month_of_year":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"start_date":{"type":"string","maxLength":10},"end_date":{"type":["string","null"],"maxLength":10},"next_run_date":{"type":["string","null"],"maxLength":10},"last_run_date":{"type":["string","null"],"maxLength":10},"status":{"type":"string","enum":["active","paused","completed"],"description":"Recurring invoice schedule status"},"auto_send":{"type":"boolean"},"create_as_draft":{"type":"boolean"},"send_to":{"type":["string","null"],"maxLength":255},"payment_terms_days":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"notify_owner":{"type":"boolean"},"invoices_generated":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"last_generated_invoice_id":{"type":["string","null"],"maxLength":36},"last_error":{"type":["string","null"],"maxLength":1000},"last_error_at":{"type":["string","null"],"format":"date-time"},"metadata":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","entity_id","document_id","name","frequency","interval","start_date","status","auto_send","create_as_draft","notify_owner","invoices_generated","metadata","created_at","updated_at"],"description":"Recurring invoice schedule configuration"},"RevenueRecognitionSettingsResponse":{"type":"object","properties":{"default_method":{"type":"string","enum":["off","service_period_daily"],"default":"off","description":"Entity default for generated revenue recognition entries. Individual document lines can opt out with method=immediate.","example":"service_period_daily"}},"additionalProperties":false},"UpdateRevenueRecognitionSettings":{"type":"object","properties":{"default_method":{"type":["string","null"],"enum":["off","service_period_daily",null],"default":"off","description":"Entity default for generated revenue recognition entries. Send null to clear back to the default off behavior.","example":"service_period_daily"}},"additionalProperties":false},"RevenueRecognitionBackfillResponse":{"type":"object","properties":{"processed_documents":{"type":"number"},"generated_entries":{"type":"number"},"dry_run":{"type":"boolean"}},"required":["processed_documents","generated_entries","dry_run"]},"RevenueRecognitionReportResponse":{"type":"object","properties":{"basis":{"type":"string","enum":["recognized","deferred"]},"group_by":{"type":"string","enum":["financial_category"]},"calculation_mode":{"type":"string","enum":["recognition_entries","document_date_fallback","mixed"],"description":"How report values were calculated. recognition_entries uses generated service-period schedules; document_date_fallback uses finalized document-item totals by issue date while automation is off; mixed combines document-date fallback with explicit line-level recognition entries.","example":"recognition_entries"},"periods":{"type":"array","items":{"$ref":"#/components/schemas/RevenueRecognitionPeriod"}},"series":{"type":"array","items":{"$ref":"#/components/schemas/RevenueRecognitionSeries"}},"totals":{"type":"array","items":{"type":"number"}},"total":{"type":"number"},"currency_code":{"type":"string"},"date_from":{"type":"string"},"date_to":{"type":"string"}},"required":["basis","group_by","calculation_mode","periods","series","totals","total","currency_code","date_from","date_to"]},"RevenueRecognitionPeriod":{"type":"object","properties":{"period":{"type":"string"},"date_from":{"type":"string"},"date_to":{"type":"string"}},"required":["period","date_from","date_to"]},"RevenueRecognitionSeries":{"type":"object","properties":{"key":{"type":"string"},"financial_category_id":{"type":["string","null"]},"name":{"type":"string"},"color":{"type":["string","null"]},"values":{"type":"array","items":{"type":"number"}},"total":{"type":"number"}},"required":["key","financial_category_id","name","color","values","total"]},"RevenueRecognitionDetailsResponse":{"type":"object","properties":{"calculation_mode":{"type":"string","enum":["recognition_entries","document_date_fallback","mixed"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/RevenueRecognitionDetailRow"}},"total":{"type":"number"},"currency_code":{"type":"string"}},"required":["calculation_mode","data","total","currency_code"]},"RevenueRecognitionDetailRow":{"type":"object","properties":{"id":{"type":"string"},"document_id":{"type":"string"},"document_type":{"type":"string"},"document_number":{"type":"string"},"document_date":{"type":"string"},"document_item_id":{"type":"string"},"customer_id":{"type":["string","null"]},"customer_name":{"type":["string","null"]},"financial_category_id":{"type":["string","null"]},"financial_category_name":{"type":"string"},"currency_code":{"type":"string"},"source_amount":{"type":"number"},"recognized_amount":{"type":"number"},"period_start":{"type":"string"},"period_end":{"type":"string"},"service_period_start":{"type":"string"},"service_period_end":{"type":"string"},"method":{"type":"string"}},"required":["id","document_id","document_type","document_number","document_date","document_item_id","customer_id","customer_name","financial_category_id","financial_category_name","currency_code","source_amount","recognized_amount","period_start","period_end","service_period_start","service_period_end","method"]},"SendPaymentReminderResponse":{"type":"object","properties":{"message_id":{"type":"string","description":"Email provider message id, or a sandbox skip id when delivery was skipped.","example":"msg_123"},"status":{"type":"string","enum":["sent","skipped"],"description":"Reminder delivery status.","example":"sent"},"to":{"type":"string","format":"email","description":"Recipient email address.","example":"customer@example.com"},"subject":{"type":"string","description":"Resolved subject that was sent.","example":"Payment reminder"},"overdue_invoice_count":{"type":"integer","minimum":0,"description":"Number of overdue invoices included in the reminder.","example":2},"invoice_ids":{"type":"array","items":{"type":"string"},"description":"Invoice ids included in the reminder.","example":["inv_123","inv_456"]},"sandbox_skip_delivery":{"type":"boolean","description":"Present when sandbox delivery was intentionally skipped.","example":true}},"required":["message_id","status","to","subject","overdue_invoice_count","invoice_ids"]},"SendPaymentReminderBody":{"type":"object","properties":{"customer_id":{"type":"string","minLength":1,"description":"Customer id to send one payment reminder for. All overdue unpaid invoices for the customer are included.","example":"cust_123"},"recipient_email":{"type":["string","null"],"format":"email","description":"Optional recipient override for this manual reminder. When omitted, the customer's saved email is used.","example":"customer@example.com"},"subject":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Optional subject override. When omitted, configured payment reminder defaults are used.","example":"Payment reminder"},"body_text":{"type":["string","null"],"minLength":1,"description":"Optional reminder body override. Supports reminder smart codes such as {invoice_list}."},"payment_instructions":{"type":["string","null"],"description":"Optional payment instructions override. Bank account placeholders are resolved before sending."},"locale":{"type":["string","null"],"enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS",null],"description":"Override reminder formatting locale. When omitted, the explicit language locale or entity locale is used.","example":"en-US"},"language":{"anyOf":[{"type":"string","enum":["en","de","sl","it","fr","es","pt","nl","pl","hr","sv","fi","et","bg","cs","sk","nb","is"]},{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"]},{"type":"null"}],"description":"Override reminder content language. Accepts a UI language code or full locale. When locale is omitted, this also controls date and number formatting.","example":"en-US"},"sandbox_skip_delivery":{"type":"boolean","default":false,"description":"Sandbox-only dry run. Builds the reminder response without delivering email.","example":false}},"required":["customer_id"],"additionalProperties":false},"WhiteLabelConfig":{"type":"object","properties":{"slug":{"type":"string","description":"Unique identifier for the white-label","example":"space-invoices"},"name":{"type":"string","description":"Display name of the white-label","example":"Space Invoices"},"environment":{"type":"string","enum":["production","sandbox"],"description":"White-label environment resolved for this domain or account.","example":"production"},"hidden_features":{"type":"array","items":{"type":"string"},"description":"UI capabilities and standalone action controls hidden for this white-label. Empty array means all configured capability families and controls stay visible. Example values include \"developer_tools\", \"documents.credit_notes\", and \"actions.documents.credit_notes.create_from_invoice\".","example":["developer_tools"]},"billing_enabled":{"type":"boolean","description":"Whether billing-related settings and subscription UI should be shown for this white-label.","example":true},"account_users_full_ui_enabled":{"type":"boolean","description":"Whether account users bypass white-label UI hiding and keep access to the full product UI on this brand.","example":true},"hide_new_features_by_default":{"type":"boolean","description":"Whether white-label-visible features added after the last capabilities review stay hidden until reviewed.","example":false},"reviewed_feature_catalog_ids":{"type":"array","items":{"type":"string"},"description":"Catalog IDs reviewed during the last explicit capabilities save.","example":["developer_tools","documents.estimates","actions.documents.invoice.create"]},"theme":{"type":["object","null"],"properties":{"primary":{"type":"string","description":"Primary color in HSL format (e.g., '220 70% 50%')","example":"220 70% 50%"},"radius":{"type":"string","description":"Border radius (e.g., '0.5rem', '0.75rem')","example":"0.5rem"}},"description":"Theme configuration (default colors for embed-sdk). Null means use defaults."},"app_name":{"type":["string","null"],"description":"Installed app name for PWA/browser surfaces. Null means use the white-label name.","example":"Apollo"},"short_name":{"type":["string","null"],"description":"Short installed app name for compact browser/PWA surfaces. Null means use the white-label name.","example":"Apollo"},"logo_url":{"type":["string","null"],"format":"uri","description":"Branded logo URL used for app install surfaces when configured.","example":"https://cdn.example.com/apollo-logo.png"},"favicon_url":{"type":["string","null"],"format":"uri","description":"Branded favicon/app icon URL used for browser and install surfaces when configured.","example":"https://cdn.example.com/apollo-favicon.png"},"theme_color":{"type":["string","null"],"description":"Resolved CSS theme color for install surfaces and browser UI.","example":"hsl(188 74% 36%)"},"analytics":{"type":"object","properties":{"posthog_key":{"type":["string","null"],"description":"Public PostHog project key for this white-label. Null means browser analytics are disabled.","example":null},"posthog_host":{"type":["string","null"],"description":"PostHog API host for this white-label. Null means use the default PostHog host.","example":"https://eu.i.posthog.com"},"posthog_track_embeds":{"type":"boolean","description":"Whether PostHog may initialize on embedded app routes for this white-label.","example":false}},"required":["posthog_key","posthog_host","posthog_track_embeds"],"description":"Analytics configuration for this white-label."},"hal_app_id":{"type":["string","null"],"description":"Hal app ID for chat widget loading. Null means no Hal integration.","example":null},"support_email":{"type":["string","null"],"format":"email","description":"Support contact email for this white-label. Null means no configured support email.","example":"support@example.com"},"google_tag_id":{"type":["string","null"],"description":"Google tag ID used for conversion tracking. Null means Google tracking is disabled.","example":"G-XXXXXXXXXX"}},"required":["slug","name","hidden_features","billing_enabled","account_users_full_ui_enabled","hide_new_features_by_default","reviewed_feature_catalog_ids","app_name","short_name","logo_url","favicon_url","theme_color","analytics","hal_app_id","support_email","google_tag_id"],"description":"White-label configuration for the current domain","example":{"slug":"space-invoices","name":"Space Invoices","environment":"production","hidden_features":[],"billing_enabled":false,"account_users_full_ui_enabled":true,"hide_new_features_by_default":false,"reviewed_feature_catalog_ids":[],"theme":null,"app_name":"Space Invoices","short_name":"Space Invoices","logo_url":null,"favicon_url":null,"theme_color":null,"analytics":{"posthog_key":null,"posthog_host":"https://eu.i.posthog.com","posthog_track_embeds":false},"hal_app_id":null,"support_email":null,"google_tag_id":null}},"CurrentSubscription":{"type":"object","properties":{"plan":{"$ref":"#/components/schemas/WhiteLabelPlan"},"status":{"type":"string","description":"Subscription status","example":"active"},"billing_interval":{"type":["string","null"],"description":"Current billing interval","example":"monthly"},"current_period_start":{"type":"string","description":"Current period start date (ISO 8601)","example":"2025-01-01T00:00:00.000Z"},"current_period_end":{"type":"string","description":"Current period end date (ISO 8601)","example":"2025-01-31T23:59:59.999Z"},"payment_provider":{"type":"string","enum":["stripe","paypal","bank","braintree"],"description":"Billing provider used for this subscription","example":"stripe"},"currency_code":{"type":"string","enum":["EUR","USD"],"description":"Currency used for subscription billing.","example":"EUR"},"billing_profile":{"type":"string","enum":["default","us_company"],"description":"Resolved billing profile for this subscription.","example":"default"},"allowed_payment_providers":{"type":"array","items":{"type":"string","enum":["stripe","paypal","bank"]},"description":"Payment providers allowed for the resolved billing profile.","example":["stripe","paypal","bank"]},"stripe_publishable_key_kind":{"type":"string","enum":["default","us_company"],"description":"Frontend-safe selector for which Stripe publishable key to use.","example":"default"},"bank_reference":{"type":["string","null"],"description":"Stable bank-transfer payment reference for Apollo subscriptions","example":"SI00 AP7F3A1B2C4D6"},"billing_email":{"type":["string","null"],"description":"Billing email used for subscription notifications and invoices","example":"billing@example.com"},"coupon_code":{"type":["string","null"],"description":"Applied saved coupon code for the base plan price, e.g. \"COUPON_50\".","example":"COUPON_50"},"trial_ends_at":{"type":["string","null"],"description":"Trial end date (ISO 8601). Null if not on trial.","example":null},"trial_days_remaining":{"type":["integer","null"],"description":"Days remaining in trial. Null if not on trial.","example":null},"trial_started_now":{"type":"boolean","description":"True only when this request created the trial subscription.","example":false},"cancel_at":{"type":["string","null"],"description":"Scheduled cancellation date (ISO 8601). Null if not scheduled.","example":null},"scheduled_change":{"type":["object","null"],"properties":{"plan":{"$ref":"#/components/schemas/WhiteLabelPlan"},"billing_interval":{"type":["string","null"],"description":"Scheduled billing interval once the change takes effect","example":"monthly"},"effective_at":{"type":"string","description":"When the scheduled change takes effect (ISO 8601)","example":"2025-01-31T23:59:59.999Z"}},"required":["plan","billing_interval","effective_at"]},"payment_method":{"type":["object","null"],"properties":{"last4":{"type":["string","null"],"example":"4242"},"brand":{"type":["string","null"],"example":"visa"},"has_card":{"type":"boolean","example":true}},"required":["last4","brand","has_card"]},"store_billing":{"anyOf":[{"$ref":"#/components/schemas/StoreBilling"},{"type":"null"}]},"usage":{"$ref":"#/components/schemas/UsageStats"}},"required":["plan","status","billing_interval","current_period_start","current_period_end","payment_provider","currency_code","billing_profile","allowed_payment_providers","stripe_publishable_key_kind","bank_reference","billing_email","coupon_code","trial_ends_at","trial_days_remaining","trial_started_now","cancel_at","scheduled_change","payment_method","store_billing","usage"],"description":"Current entity subscription with usage stats","example":{"plan":{"id":"plan_123abc","slug":"advanced","name":"Advanced","billing_interval":"monthly","base_price_cents":999,"limits":{"documents_per_month":null,"invoices_per_month":500,"overage_price_cents":null,"e_invoicing_sends_included":10,"e_invoicing_send_price_cents":10},"features":["invoices","estimates","customers","items","pdf_export","business_units","financial_categories","furs","eslog"],"is_free":false,"display_order":1},"status":"active","billing_interval":"monthly","current_period_start":"2025-01-01T00:00:00.000Z","current_period_end":"2025-01-31T23:59:59.999Z","billing_email":"billing@example.com","trial_ends_at":null,"trial_days_remaining":null,"trial_started_now":false,"cancel_at":null,"scheduled_change":null,"payment_method":{"last4":"4242","brand":"visa","has_card":true},"store_billing":{"connected_stores":3,"included_stores":1,"billable_extra_stores":2,"invoices_included_from_extra_stores":2000,"extra_store_price_cents_monthly":599,"extra_store_price_cents_yearly":5900},"usage":{"documents_count":42,"documents_limit":null,"invoices_count":8,"invoices_limit":2500,"e_invoicing_send_count":2,"e_invoicing_sends_included":10,"period_start":"2025-01-01T00:00:00.000Z","period_end":"2025-01-31T23:59:59.999Z"}}},"WhiteLabelPlan":{"type":"object","properties":{"id":{"type":"string","description":"Unique plan ID","example":"plan_123abc"},"slug":{"type":"string","description":"Plan slug","example":"starter"},"name":{"type":"string","description":"Display name","example":"Starter"},"billing_interval":{"type":["string","null"],"description":"Billing interval: \"monthly\", \"yearly\", or null for free plans","example":"monthly"},"base_price_cents":{"type":["integer","null"],"description":"Price in cents. Null for free plans.","example":900},"currency_code":{"type":"string","enum":["EUR","USD"],"description":"Currency used for this plan in the current billing profile.","example":"EUR"},"limits":{"anyOf":[{"$ref":"#/components/schemas/PlanLimits"},{"type":"null"}]},"features":{"type":"array","items":{"type":"string"},"description":"List of features included. Empty array means all features.","example":["invoices","estimates","customers","items","pdf_export"]},"is_free":{"type":"boolean","description":"Whether this is a free plan","example":false},"display_order":{"type":"integer","description":"Display order for sorting","example":1}},"required":["id","slug","name","billing_interval","base_price_cents","currency_code","limits","features","is_free","display_order"],"description":"A subscription plan for a white-label product"},"PlanLimits":{"type":"object","properties":{"documents_per_month":{"type":["integer","null"],"description":"Maximum documents per month (backward compat). Null means unlimited.","example":null},"invoices_per_month":{"type":["integer","null"],"description":"Maximum invoices per month. Null means unlimited.","example":500},"overage_price_cents":{"type":["integer","null"],"description":"Overage price in cents per document. Null means hard block.","example":null},"annual_price_cents":{"type":["integer","null"],"description":"Explicit yearly plan price in cents. Null falls back to computed yearly pricing.","example":12900},"included_store_count":{"type":["integer","null"],"description":"Number of connected stores included in the base plan.","example":1},"extra_store_price_cents":{"type":["integer","null"],"description":"Monthly price in cents for each additional connected store.","example":599},"extra_store_annual_price_cents":{"type":["integer","null"],"description":"Yearly price in cents for each additional connected store.","example":5900},"extra_store_invoices_per_month":{"type":["integer","null"],"description":"Pooled invoice allowance added by each additional store.","example":1000},"e_invoicing_sends_included":{"type":["integer","null"],"description":"Peppol sends included per month. Null means the plan does not configure Peppol metering.","example":0},"e_invoicing_send_price_cents":{"type":["integer","null"],"description":"Overage price in cents per successful live Peppol send.","example":10}},"required":["documents_per_month","invoices_per_month","overage_price_cents","annual_price_cents","included_store_count","extra_store_price_cents","extra_store_annual_price_cents","extra_store_invoices_per_month","e_invoicing_sends_included","e_invoicing_send_price_cents"]},"StoreBilling":{"type":"object","properties":{"connected_stores":{"type":"integer","example":3},"included_stores":{"type":"integer","example":1},"billable_extra_stores":{"type":"integer","example":2},"invoices_included_from_extra_stores":{"type":"integer","example":2000},"extra_store_price_cents_monthly":{"type":["integer","null"],"example":599},"extra_store_price_cents_yearly":{"type":["integer","null"],"example":5900}},"required":["connected_stores","included_stores","billable_extra_stores","invoices_included_from_extra_stores","extra_store_price_cents_monthly","extra_store_price_cents_yearly"]},"UsageStats":{"type":"object","properties":{"documents_count":{"type":"integer","description":"Documents created this period","example":42},"documents_limit":{"type":["integer","null"],"description":"Documents limit for current plan. Null means unlimited.","example":null},"invoices_count":{"type":"integer","description":"Invoices created this period (invoices, credit notes, advance invoices)","example":8},"invoices_limit":{"type":["integer","null"],"description":"Invoice limit for current plan. Null means unlimited.","example":500},"e_invoicing_send_count":{"type":"integer","default":0,"description":"Peppol/e-invoicing sends this period.","example":2},"e_invoicing_sends_included":{"type":["integer","null"],"default":null,"description":"Included Peppol/e-invoicing sends for current plan. Null means not configured.","example":10},"period_start":{"type":"string","description":"Current period start date (ISO 8601)","example":"2025-01-01T00:00:00.000Z"},"period_end":{"type":"string","description":"Current period end date (ISO 8601)","example":"2025-01-31T23:59:59.999Z"}},"required":["documents_count","documents_limit","invoices_count","invoices_limit","period_start","period_end"],"description":"Usage statistics for current billing period"},"AvailablePlans":{"type":"object","properties":{"plans":{"type":"array","items":{"$ref":"#/components/schemas/WhiteLabelPlan"},"description":"Available plans for the current white-label"},"current_plan_slug":{"type":["string","null"],"description":"Current plan slug (null if no subscription)","example":"free"},"currency_code":{"type":"string","enum":["EUR","USD"],"description":"Currency used for the returned plans.","example":"EUR"},"billing_profile":{"type":"string","enum":["default","us_company"],"description":"Resolved billing profile for the current entity.","example":"default"},"allowed_payment_providers":{"type":"array","items":{"type":"string","enum":["stripe","paypal","bank"]},"description":"Payment providers allowed for the resolved billing profile.","example":["stripe","paypal","bank"]},"stripe_publishable_key_kind":{"type":"string","enum":["default","us_company"],"description":"Frontend-safe selector for which Stripe publishable key to use.","example":"default"}},"required":["plans","current_plan_slug","currency_code","billing_profile","allowed_payment_providers","stripe_publishable_key_kind"],"description":"Available subscription plans for the current white-label","example":{"plans":[{"id":"plan_simple","slug":"simple","name":"Simple","billing_interval":"monthly","base_price_cents":499,"limits":{"documents_per_month":null,"invoices_per_month":10,"overage_price_cents":null},"features":["invoices","estimates","customers","items","pdf_export","email_sending"],"is_free":false,"display_order":0},{"id":"plan_advanced","slug":"advanced","name":"Advanced","billing_interval":"monthly","base_price_cents":999,"limits":{"documents_per_month":null,"invoices_per_month":500,"overage_price_cents":null},"features":["invoices","estimates","customers","items","pdf_export","business_units","financial_categories","furs","eslog"],"is_free":false,"display_order":1}],"current_plan_slug":"simple"}},"FeatureCheck":{"type":"object","properties":{"feature":{"type":"string","description":"Feature being checked","example":"furs"},"allowed":{"type":"boolean","description":"Whether the feature is allowed on the current plan","example":true},"requires_upgrade":{"type":"boolean","description":"Whether an upgrade is needed to access this feature","example":false},"upgrade_plan_slug":{"type":["string","null"],"description":"Minimum plan slug that includes this feature (if requires_upgrade is true)","example":"starter"}},"required":["feature","allowed","requires_upgrade","upgrade_plan_slug"],"description":"Feature access check result","example":{"feature":"furs","allowed":true,"requires_upgrade":false,"upgrade_plan_slug":null}},"LimitCheck":{"type":"object","properties":{"resource":{"type":"string","description":"Resource being checked","example":"documents"},"allowed":{"type":"boolean","description":"Whether creating more of this resource is allowed","example":true},"usage":{"type":"integer","description":"Current usage count","example":42},"limit":{"type":["integer","null"],"description":"Current limit. Null means unlimited.","example":100},"percentage":{"type":"number","description":"Usage as percentage of limit (0-100). 0 if unlimited.","example":42}},"required":["resource","allowed","usage","limit","percentage"],"description":"Resource limit check result","example":{"resource":"documents","allowed":true,"usage":42,"limit":100,"percentage":42}},"WLUpdateBillingEmailRequest":{"type":"object","properties":{"billing_email":{"type":["string","null"],"format":"email","example":"billing@example.com"}},"required":["billing_email"],"additionalProperties":false},"CurrentUsageResponse":{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/Subscription"},"usage":{"$ref":"#/components/schemas/SIUsageStats"},"limits":{"type":"object","properties":{"entities":{"type":["number","null"],"description":"Max entities for free tier (null for metered)","example":1},"documents_per_month":{"type":["number","null"],"description":"Max docs per month for free tier (null for metered)","example":10}},"required":["entities","documents_per_month"]},"is_over_limit":{"type":"boolean","example":false}},"required":["subscription","usage","limits","is_over_limit"],"description":"Current subscription and usage for Space Invoices account","example":{"subscription":{"id":"sub_123abc","account_id":"acc_456def","tier":"free","spending_limit_cents":5000,"is_internal":false,"created_at":"2025-01-01T00:00:00.000Z","updated_at":"2025-01-01T00:00:00.000Z"},"usage":{"documents_count":5,"e_invoicing_send_count":0,"entities_active":1,"period_start":"2025-01-01T00:00:00.000Z","period_end":"2025-01-31T23:59:59.999Z"},"limits":{"entities":1,"documents_per_month":10},"is_over_limit":false}},"Subscription":{"type":"object","properties":{"id":{"type":"string","example":"sub_123abc"},"account_id":{"type":"string","example":"acc_456def"},"tier":{"type":"string","enum":["free","metered"],"example":"free"},"spending_limit_cents":{"type":["number","null"],"example":5000},"is_internal":{"type":"boolean","example":false},"created_at":{"type":"string","example":"2025-01-01T00:00:00.000Z"},"updated_at":{"type":"string","example":"2025-01-01T00:00:00.000Z"}},"required":["id","account_id","tier","spending_limit_cents","is_internal","created_at","updated_at"]},"SIUsageStats":{"type":"object","properties":{"documents_count":{"type":"number","example":42},"e_invoicing_send_count":{"type":"number","default":0,"example":3},"entities_active":{"type":"number","example":1},"period_start":{"type":"string","example":"2025-01-01T00:00:00.000Z"},"period_end":{"type":"string","example":"2025-01-31T23:59:59.999Z"}},"required":["documents_count","entities_active","period_start","period_end"]},"UpdateSpendingLimitResponse":{"type":"object","properties":{"spending_limit_cents":{"type":["number","null"],"example":10000}},"required":["spending_limit_cents"],"description":"Updated spending limit","example":{"spending_limit_cents":10000}},"UpdateSpendingLimitRequest":{"type":"object","properties":{"spending_limit_cents":{"type":["number","null"],"minimum":0,"example":10000}},"required":["spending_limit_cents"],"additionalProperties":false,"description":"Request to update spending limit for metered tier","example":{"spending_limit_cents":10000}},"EntityLimitCheck":{"type":"object","properties":{"can_create":{"type":"boolean","example":true},"current_count":{"type":"number","example":1},"limit":{"type":["number","null"],"example":1}},"required":["can_create","current_count","limit"]},"ShopifyAuthorizeResponse":{"type":"object","properties":{"redirect_url":{"type":"string","format":"uri"}},"required":["redirect_url"]},"ShopifyResumeInstallResponse":{"type":"object","properties":{"redirect_url":{"type":"string","format":"uri"},"entity_id":{"type":"string"},"frontend_origin":{"type":["string","null"],"format":"uri"}},"required":["redirect_url","entity_id"]},"ShopifyResumeInstallRequest":{"type":"object","properties":{"shop":{"type":"string","minLength":1}},"required":["shop"]},"SyncShopifyOrdersResponse":{"type":"object","properties":{"imported":{"type":"integer"},"updated":{"type":"integer"},"queued_for_processing":{"type":"integer"},"total_seen":{"type":"integer"},"window_start":{"type":"string","format":"date-time"},"window_end":{"type":"string","format":"date-time"},"complete":{"type":"boolean"},"truncated":{"type":"boolean"},"pages_fetched":{"type":"integer"},"completion_state":{"type":"string","enum":["complete","resumable"]},"next_cursor":{"type":"string"}},"required":["imported","updated","queued_for_processing","total_seen","window_start"]},"OrderIntegration":{"allOf":[{"$ref":"#/components/schemas/OrderIntegrationBase"},{"type":"object","properties":{}}],"description":"Order Integration"},"OrderIntegrationBase":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"entity_id":{"type":"string","maxLength":36},"name":{"type":"string","maxLength":255},"source":{"type":"string","enum":["shopify","woocommerce","manual"],"description":"Integration source platform"},"is_active":{"type":"boolean"},"shop_domain":{"type":["string","null"],"maxLength":255},"scopes":{"type":["string","null"],"maxLength":1000},"auto_process":{"type":"boolean"},"auto_process_on":{"type":"string","enum":["created","paid","fulfilled"],"description":"When to automatically process orders into invoices"},"default_payment_type":{"type":["string","null"],"maxLength":20},"send_invoice_email":{"type":"boolean"},"send_estimate_email":{"type":"boolean"},"attach_pdf_to_email":{"type":"boolean"},"issue_invoice_for_bank":{"type":"boolean"},"issue_invoice_on_complete":{"type":"boolean"},"auto_process_delay_seconds":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"auto_reissue_on_update":{"type":"boolean"},"locale":{"type":["string","null"],"maxLength":10},"business_unit_id":{"type":["string","null"],"maxLength":36},"business_premise_id":{"type":["string","null"],"maxLength":36},"electronic_device_id":{"type":["string","null"],"maxLength":36},"metadata":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","entity_id","name","source","is_active","auto_process","auto_process_on","send_invoice_email","send_estimate_email","attach_pdf_to_email","issue_invoice_for_bank","issue_invoice_on_complete","auto_process_delay_seconds","auto_reissue_on_update","metadata","created_at","updated_at"],"description":"Order integration connection information"},"Order":{"allOf":[{"$ref":"#/components/schemas/OrderBase"},{"type":"object","properties":{}}],"description":"Order"},"OrderCustomer":{"type":"object","properties":{"phone":{"type":"string"},"company_name":{"type":"string"},"tax_number":{"type":"string"},"company_number":{"type":"string"},"is_business":{"type":"boolean"},"notes":{"type":"string"}}},"OrderAddress":{"type":"object","properties":{"address":{"type":"string"},"address_2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"post_code":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"}}},"OrderItem":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"number"},"price":{"type":"number"},"gross_price":{"type":"number"},"total":{"type":"number"},"total_with_tax":{"type":"number"},"tax_rate":{"type":"number"},"taxes":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number"}},"required":["rate"]}},"sku":{"type":"string"},"source_id":{"type":"string"},"discount":{"type":"number"},"unit":{"type":"string"},"kind":{"type":"string","enum":["line_item","shipping"]}},"required":["name","quantity","price","total","total_with_tax"]},"OrderTransaction":{"type":"object","properties":{"amount":{"type":"number"},"gateway":{"type":"string"},"status":{"type":"string"},"tag":{"type":"string"},"date":{"type":"string"},"note":{"type":"string"}},"required":["amount","gateway","status","date"]},"OrderBase":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"entity_id":{"type":"string","maxLength":36},"order_integration_id":{"type":"string","maxLength":36},"source":{"type":"string","enum":["shopify","woocommerce","manual"],"description":"Order source platform"},"source_id":{"type":"string","maxLength":255},"source_order_number":{"type":["string","null"],"maxLength":100},"status":{"type":"string","enum":["pending","processing","invoiced","estimated","cancelled","failed"],"description":"Order processing status"},"paid":{"type":"boolean"},"paid_at":{"type":["string","null"],"format":"date-time"},"fulfilled":{"type":"boolean"},"fulfilled_at":{"type":["string","null"],"format":"date-time"},"cancelled":{"type":"boolean"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"refunded":{"type":"boolean"},"refunded_at":{"type":["string","null"],"format":"date-time"},"customer_name":{"type":["string","null"],"maxLength":255},"customer_email":{"type":["string","null"],"maxLength":255},"customer":{"anyOf":[{"$ref":"#/components/schemas/OrderCustomer"},{"type":"null"}]},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/OrderAddress"},{"type":"null"}]},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/OrderAddress"},{"type":"null"}]},"customer_id":{"type":["string","null"],"maxLength":36},"currency_code":{"type":"string","maxLength":3},"total":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_with_tax":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_discount":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_shipping":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"}},"payment_status":{"type":"string","enum":["unpaid","paid","partially_paid","refunded"],"description":"Order payment status"},"payment_method":{"type":["string","null"],"maxLength":50},"payment_gateway":{"type":["string","null"],"maxLength":100},"invoice_id":{"type":["string","null"],"maxLength":36},"estimate_id":{"type":["string","null"],"maxLength":36},"process_after":{"type":["string","null"],"format":"date-time"},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/OrderTransaction"}},"complete":{"type":"boolean"},"items_changed_after_processing":{"type":"boolean"},"raw_data":{"type":["object","null"],"additionalProperties":{}},"source_event_id":{"type":["string","null"],"maxLength":255},"error":{"type":["string","null"],"maxLength":2000},"ordered_at":{"type":["string","null"],"format":"date-time"},"processed_at":{"type":["string","null"],"format":"date-time"},"metadata":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"deleted_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","entity_id","order_integration_id","source","source_id","status","paid","fulfilled","cancelled","refunded","customer","billing_address","shipping_address","currency_code","total","total_with_tax","total_discount","total_shipping","items","payment_status","transactions","complete","items_changed_after_processing","metadata","created_at","updated_at"],"description":"Order information"},"StripeAppAuthorizeResponse":{"type":"object","properties":{"redirect_url":{"type":"string","format":"uri","description":"URL to redirect the user to for authentication","example":"https://v2.getapollo.io/stripe-app-link?state=sa_state_abc123"}},"required":["redirect_url"]},"StripeAppWebhookResponse":{"type":"object","properties":{"received":{"type":"boolean","description":"Whether the webhook was received successfully"}},"required":["received"]},"StripeAppConnection":{"type":"object","properties":{"id":{"type":"string","description":"Connection ID","example":"sac_507f1f77bcf86cd799439011"},"stripe_account_id":{"type":"string","description":"Connected Stripe account ID","example":"acct_1234567890"},"entity_id":{"type":"string","description":"Connected Space Invoices entity ID","example":"ent_507f1f77bcf86cd799439011"},"white_label_id":{"type":"string","description":"White-label context for this connection","example":"wl_apollo"},"auto_invoice_config":{"type":"object","properties":{"enabled":{"type":"boolean"},"events":{"type":"array","items":{"type":"string"}},"default_note":{"type":"string"}},"required":["enabled","events"],"description":"Auto-invoice configuration"},"created_at":{"type":"string","format":"date-time","description":"When the connection was created"}},"required":["id","stripe_account_id","entity_id","white_label_id","auto_invoice_config","created_at"]},"StripeAppSettings":{"type":"object","properties":{"auto_invoice_enabled":{"type":"boolean","description":"Whether auto-invoicing is enabled"},"auto_invoice_events":{"type":"array","items":{"type":"string"},"description":"Stripe event types that trigger auto-invoice creation"},"default_note":{"type":["string","null"],"description":"Default note for auto-created invoices"},"default_tax_rate":{"type":["number","null"],"description":"Default tax rate applied when Stripe data has no tax info"}},"required":["auto_invoice_enabled","auto_invoice_events","default_note","default_tax_rate"]},"StripeAppInvoice":{"type":"object","properties":{"id":{"type":"string","description":"Space Invoices invoice ID"},"number":{"type":["string","null"],"description":"Invoice number"},"status":{"type":"string","description":"Invoice status"},"total":{"type":"number","description":"Invoice total amount"},"currency":{"type":"string","description":"Currency code"},"public_url":{"type":["string","null"],"format":"uri","description":"Public URL to view the invoice"},"fiscalization_status":{"type":["string","null"],"description":"Fiscalization/compliance status if applicable"},"created_at":{"type":"string","format":"date-time","description":"When the invoice was created"}},"required":["id","number","status","total","currency","public_url","fiscalization_status","created_at"]},"StripeAppInvoiceList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StripeAppInvoice"}}},"required":["data"]},"LegacyAuthResponse":{"type":"object","properties":{"organizations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Legacy organization ID"},"name":{"type":"string","description":"Organization name"},"country":{"type":["string","null"],"description":"Country"},"tax_number":{"type":["string","null"],"description":"Tax number"},"created_at":{"type":"string","description":"Creation date"},"already_migrated":{"type":"boolean","description":"Whether this org has already been migrated"},"migrated_environment":{"type":["string","null"],"description":"Environment it was migrated to"}},"required":["id","name","country","tax_number","created_at","already_migrated","migrated_environment"]}},"legacy_session_id":{"type":"string","description":"Temporary server-side legacy session identifier used for async file migration"}},"required":["organizations","legacy_session_id"]},"LegacyAuthRequest":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email for legacy Space Invoices account","example":"user@example.com"},"password":{"type":"string","minLength":1,"description":"Password for legacy Space Invoices account"}},"required":["email","password"],"additionalProperties":false},"CreateMigrationJobResponse":{"type":"object","properties":{"id":{"type":"string","description":"Job ID"},"status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"Migration job status"},"message":{"type":"string","description":"Status message"}},"required":["id","status","message"]},"CreateMigrationJobRequest":{"type":"object","properties":{"legacy_org_id":{"type":"string","minLength":1,"description":"Legacy organization ID to migrate"},"legacy_session_id":{"type":"string","minLength":1,"description":"Temporary legacy session ID created after legacy authentication"},"environment":{"type":"string","enum":["live","sandbox"],"description":"Target environment","example":"sandbox"},"confirm_unsupported_data":{"type":"boolean","description":"Explicit user confirmation that unsupported legacy data will need manual setup"}},"required":["legacy_org_id","legacy_session_id","environment"],"additionalProperties":false},"MigrationJobListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MigrationJobResponse"}}},"required":["data"]},"MigrationJobResponse":{"type":"object","properties":{"id":{"type":"string","description":"Job ID"},"legacy_org_id":{"type":"string","description":"Legacy organization ID"},"environment":{"type":"string","description":"Target environment"},"entity_id":{"type":["string","null"],"description":"Created entity ID (on completion)"},"status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"Migration job status"},"step":{"type":["string","null"],"description":"Current step label"},"step_number":{"type":"number","description":"Current step number"},"total_steps":{"type":"number","description":"Total number of steps"},"progress_detail":{"type":["string","null"],"description":"Progress detail"},"error":{"type":["string","null"],"description":"User-friendly error message"},"created_at":{"type":"string","description":"Job creation date"},"started_at":{"type":["string","null"],"description":"Job start date"},"completed_at":{"type":["string","null"],"description":"Job completion date"}},"required":["id","legacy_org_id","environment","entity_id","status","step","step_number","total_steps","progress_detail","error","created_at","started_at","completed_at"]}},"parameters":{"RequestId":{"name":"X-Request-Id","in":"header","required":false,"description":"Stable identifier for authenticated document creation and expense-payment creation. For 24 hours after the first request, retrying the same operation with the same body and request ID replays the original status and response without creating a duplicate document or payment. Reusing it with a different body during that window returns `409 idempotency_key_mismatch`. After 24 hours, the request ID is expired and reuse starts a new operation. See the [idempotency guide](https://docs.spaceinvoices.com/guides/idempotency/).","schema":{"type":"string","maxLength":100,"example":"order_123:create_invoice"}}}},"paths":{"/health/live":{"get":{"operationId":"livenessCheck","tags":["Health"],"responses":{"200":{"description":"Process is alive"}}}},"/health/ready":{"get":{"operationId":"readinessCheck","tags":["Health"],"responses":{"200":{"description":"Service is ready to accept traffic"},"503":{"description":"Service is not ready to accept traffic"}}}},"/health":{"get":{"operationId":"healthCheck","tags":["Health"],"responses":{"200":{"description":"Service is healthy"},"503":{"description":"Service is unhealthy"}}}},"/":{"get":{"operationId":"getIndex","tags":["Index"],"responses":{"200":{"description":"OK"}}}},"/locale/detect":{"get":{"operationId":"detectLocale","tags":["Locale"],"responses":{"200":{"description":"Detected language and country based on IP geolocation"}}}},"/invoices/shareable/{shareableId}":{"get":{"operationId":"getShareableInvoice","summary":"View shareable invoice","description":"Retrieve invoice data using a shareable token. No authentication required. Returns full invoice data for rendering.","security":[],"tags":["Invoices"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"}],"responses":{"200":{"description":"Invoice data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"},"examples":{"200":{"value":{"id":"inv_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"inv_item_6595a27b5d35015c3ef0c402","invoice_id":"inv_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"inv_item_6595a27b5d35015c3ef0c403","invoice_id":"inv_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2025-04-15T00:00:00.000Z","total_paid":0,"total_due":36600,"paid_in_full":false,"furs":null,"fina":null},"description":"Complete invoice response with all fields"}}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/invoices/shareable/{shareableId}/html":{"get":{"operationId":"getShareableInvoiceHtml","summary":"Get shareable invoice as HTML","description":"Get invoice as HTML preview using a shareable token. No authentication required. Supports multiple languages via locale query parameter.","security":[],"tags":["Invoices"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale."},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale.","name":"locale","in":"query"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Language for document labels/translations. Defaults to locale value. Use to get entity-locale formatting with different-language labels."},"required":false,"description":"Language for document labels/translations. Defaults to locale value. Use to get entity-locale formatting with different-language labels.","name":"language","in":"query"}],"responses":{"200":{"description":"Rendered document (HTML)","content":{"text/html":{"schema":{"type":"string","description":"Fully formatted HTML document ready for display"}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/invoices/shareable/{shareableId}/pdf":{"get":{"operationId":"getShareableInvoicePdf","summary":"Download shareable invoice as PDF","description":"Download invoice as PDF using a shareable token. No authentication required. Supports multiple languages via locale query parameter.","security":[],"tags":["Invoices"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale."},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale.","name":"locale","in":"query"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Language for document labels/translations. Defaults to locale value. Use to get entity-locale formatting with different-language labels."},"required":false,"description":"Language for document labels/translations. Defaults to locale value. Use to get entity-locale formatting with different-language labels.","name":"language","in":"query"}],"responses":{"200":{"description":"PDF document","content":{"application/pdf":{"schema":{"type":"string","format":"binary","description":"PDF document binary"}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/invoices/shareable/{shareableId}/eslog":{"get":{"operationId":"getShareableInvoiceEslog","summary":"Download shareable invoice as e-SLOG XML","description":"Download invoice as e-SLOG 2.0 XML (Slovenian electronic invoice format) using a shareable token. No authentication required. Only available for Slovenian entities with valid e-SLOG validation.","security":[],"tags":["Invoices"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"}],"responses":{"200":{"description":"e-SLOG XML document","content":{"application/xml":{"schema":{"type":"string","description":"e-SLOG 2.0 XML document"}}}},"404":{"description":"Invalid or expired shareable link, or document not valid for e-SLOG"}}}},"/invoices":{"post":{"operationId":"createInvoice","summary":"Create a new invoice","description":"Create a new invoice with line items.\nThis is the recommended endpoint for normal invoice creation. Use it when Space Invoices should calculate line totals, taxes, discounts, document totals, numbering, fiscalization, customer handling, payments, and lifecycle hooks from the supplied business inputs.\nCustomer is optional - can be omitted for retail/convenience store sales where customer information isn't needed, or added inline without referencing a customer_id.\nThe invoice number is auto-generated based on the entity's number format settings.\nTaxes are calculated automatically based on the tax rates provided.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Invoices"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"description":"Create Invoice Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoice"},"examples":{"Minimal":{"value":{"items":[{"name":"Satellite Communication Module","quantity":1,"price":1500}]},"description":"Minimal document with single item, no customer, no taxes"},"With customer":{"value":{"customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Thermal Shielding Panel","quantity":1,"price":850}]},"description":"Document with inline customer (saved to database by default)"},"With referenced customer":{"value":{"customer_id":"cus_6595a27b5d35015c3ef0c3fd","items":[{"name":"Orbital Navigation License","quantity":1,"price":5000}]},"description":"Document referencing existing customer by ID"},"With tax":{"value":{"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"name":"EVA Toolkit - Standard","quantity":8,"price":150,"taxes":[{"rate":22}]},{"name":"Orbital Navigation License","quantity":10,"price":120,"taxes":[{"rate":22}]}]},"description":"Document with tax calculations (2 items, both with 22% VAT)"},"With tax classification":{"value":{"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"name":"Mission Control Console","quantity":8,"price":150,"taxes":[{"classification":"standard"}]},{"name":"Launch Safety Manual","quantity":5,"price":20,"taxes":[{"classification":"reduced"}]}]},"description":"Document using tax classification. Rate is resolved from entity's taxes by classification (e.g., \"standard\", \"reduced\", \"zero\"). Classification must exist on entity."},"With gross price":{"value":{"customer":{"name":"Orbital Systems GmbH"},"items":[{"name":"Ground Station Antenna Array","quantity":1,"gross_price":15250,"taxes":[{"rate":22}]}]},"description":"Document with gross pricing. Net price back-calculated: 15250 / 1.22 = 12500. Use gross prices for stable totals when VIES reverse charge may apply."},"With service period":{"value":{"date":"2025-03-01","date_service":"2025-03-01","date_service_to":"2025-03-31","customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Telemetry platform hosting","quantity":1,"price":1200}]},"description":"Document with a service period. Use date_service/date_service_to for subscriptions, retainers, and revenue recognition periods."},"With line discounts":{"value":{"calculation_mode":"b2b_standard","customer":{"name":"Horizon Launch Systems Inc."},"items":[{"name":"Mission planning package","quantity":1,"price":2000,"discounts":[{"type":"percent","value":10}],"taxes":[{"rate":22}]},{"name":"Launch readiness review","quantity":1,"price":500,"discounts":[{"type":"amount","value":50}],"taxes":[{"rate":22}]}]},"description":"Document with percentage and fixed line discounts. Discounts are applied per line before tax in b2b_standard mode."},"With financial categories":{"value":{"customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Ground Segment Implementation","quantity":1,"price":2500,"financial_category_id":"fcat_services"},{"name":"Telemetry platform hosting","quantity":1,"price":300,"financial_category_id":"fcat_hosting"}]},"description":"Document with per-line financial categories for revenue-by-category reporting. Use category_assignments when assigning by request item index instead."},"With category assignments":{"value":{"customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Ground Segment Implementation","quantity":1,"price":2500},{"name":"Telemetry platform hosting","quantity":1,"price":300}],"category_assignments":[{"item_index":0,"financial_category_id":"fcat_services"},{"item_index":1,"financial_category_id":"fcat_hosting"}]},"description":"Document with category assignments by line index. This is useful when item payloads come from an external system and categories are mapped separately."},"With rounding correction":{"value":{"customer":{"name":"Legacy Payload Systems Ltd."},"expected_total_with_tax":122.01,"items":[{"name":"Imported service line","quantity":1,"price":100,"taxes":[{"rate":22}]}]},"description":"Document with expected_total_with_tax for small external rounding differences. The API calculates a rounding correction within the allowed tolerance."},"With item prefill":{"value":{"customer":{"name":"Nebula Propulsion Labs"},"items":[{"item_id":"item_6595a27b5d35015c3ef0c3fd","quantity":5}]},"description":"Document with item prefilled from catalog. Name, price, and taxes are loaded from the catalog item. Only quantity needs to be specified."},"With item prefill and overrides":{"value":{"customer":{"name":"Alex Carter"},"items":[{"item_id":"item_6595a27b5d35015c3ef0c3fd","quantity":10,"price":1400,"description":"Bulk order discount applied"},{"item_id":"item_6595a27b5d35015c3ef0c3fe","quantity":2}]},"description":"Document with multiple catalog items. First item overrides price and description from catalog. Request values always take precedence over catalog values."},"With translations":{"value":{"items":[{"name":"Satellite Communication Module","quantity":1,"price":1500,"translations":{"name":{"de-DE":"Satelliten-Kommunikationsmodul"},"description":{"de-DE":"Hochleistungs-Kommunikationsmodul fuer den Orbitaleinsatz"}}}],"note":"Thank you for your business.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."}}},"description":"Minimal document with translated document and line-item content"},"Draft":{"value":{"is_draft":true,"customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Ground Segment Implementation","quantity":1,"price":2500}]},"description":"Create a draft invoice without assigning a final sequential number or running fiscalization. Finalize it later when the customer and totals are confirmed."},"With partial payment":{"value":{"items":[{"name":"Mission Planning Services","quantity":1,"price":1500}],"payments":[{"type":"cash","amount":500}]},"description":"Invoice with partial payment - shows amount still due"},"With payment":{"value":{"items":[{"name":"Mission Planning Services","quantity":1,"price":1500}],"payments":[{"type":"bank_transfer"}]},"description":"Invoice with payment - marks invoice as paid in full"},"With linked advance invoice":{"value":{"customer_id":"cus_6595a27b5d35015c3ef0c3fd","linked_documents":["adv_6595a27b5d35015c3ef0c3fd"],"items":[{"name":"Final project delivery","quantity":1,"price":5000,"taxes":[{"rate":22}]}]},"description":"Create a final invoice and apply an existing advance invoice. The document type is inferred from the adv_ ID prefix."},"With linked delivery note":{"value":{"customer_id":"cus_6595a27b5d35015c3ef0c3fd","linked_documents":["del_6595a27b5d35015c3ef0c3fd"],"items":[{"name":"Delivered equipment","quantity":1,"price":2500}]},"description":"Create an invoice from a delivery note and link the source document for traceability."},"Force existing document link":{"value":{"customer_id":"cus_6595a27b5d35015c3ef0c3fd","linked_documents":["est_6595a27b5d35015c3ef0c3fd"],"force_linked_documents":true,"items":[{"name":"Approved estimate conversion","quantity":1,"price":3200}]},"description":"Force linking when a source estimate or delivery note was already linked and the caller intentionally wants another relation."},"With FURS operator override":{"value":{"customer":{"name":"Retail customer"},"items":[{"name":"Flight patch kit","quantity":1,"gross_price":12.2,"taxes":[{"rate":22}]}],"payments":[{"type":"cash"}],"furs":{"business_premise_name":"P1","electronic_device_name":"E1","operator_tax_number":"12345678","operator_label":"Alex Carter"}},"description":"Create a Slovenian FURS-fiscalized invoice with explicit operator fields. Cash and card payments cannot use furs.skip."},"With FINA operator override":{"value":{"customer":{"name":"Retail customer","country":"Croatia","country_code":"HR"},"items":[{"name":"Flight patch kit","quantity":1,"gross_price":12.5,"taxes":[{"rate":25}]}],"payments":[{"type":"card"}],"fina":{"business_premise_name":"PP1","electronic_device_name":"1","operator_oib":"12345678901","operator_label":"Ivan Horvat","payment_type":"card"}},"description":"Create a Croatian CIS/FINA invoice with explicit operator fields and payment type. If either operator field is sent, provide both."},"With e-SLOG validation":{"value":{"customer":{"name":"Občina Zelena Dolina","address":"Glavni trg 1","post_code":"1000","city":"Ljubljana","country":"Slovenia","country_code":"SI","tax_number":"SI12345679","company_number":"1234567890","bank_account":{"type":"iban","iban":"SI56020010012345678"}},"items":[{"name":"Ground segment maintenance","quantity":1,"price":1200,"taxes":[{"rate":22}]}],"eslog":{"validation_enabled":true}},"description":"Slovenian document with e-SLOG validation enabled. Use for B2G/e-invoicing flows after issuer and customer prerequisites are configured."},"With PT ATCUD":{"value":{"customer":{"name":"Lisboa Orbital Services","country":"Portugal","country_code":"PT"},"items":[{"name":"Ground operations service","quantity":1,"price":100,"classification":"service","taxes":[{"rate":23}]}],"pt":{"series_id":"pt_series_000000000000000000000001","operator_first_name":"Antonio","operator_last_name":"Silva","operator_tax_number":"123456789"}},"description":"Portugal document with ATCUD series and operator snapshot fields. Use after creating an active PT ATCUD series."},"Complete":{"value":{"date":"2025-03-15","note":"Thank you for your order. Equipment ships within 5 business days.","reference":"PO-2025-001","currency_code":"USD","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"items":[{"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"taxes":[{"rate":22}],"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"}},{"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"taxes":[{"rate":22}],"metadata":{"license_type":"enterprise","seats":"50"}}],"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"date_due":"2025-04-15"},"description":"Complete document with all optional fields populated"}}}}},"responses":{"201":{"description":"Created Invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"},"examples":{"Minimal":{"value":{"id":"inv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"inv_item_6595a27b5d35015c3ef0c3fd","invoice_id":"inv_6595a27b5d35015c3ef0c3fd","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":0,"total_due":1500,"paid_in_full":false,"furs":null,"fina":null},"description":"Minimal invoice response"},"With customer":{"value":{"id":"inv_6595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00002","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Nebula Propulsion Labs"},"items":[{"id":"inv_item_6595a27b5d35015c3ef0c3fe","invoice_id":"inv_6595a27b5d35015c3ef0c3fe","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Thermal Shielding Panel","description":null,"translations":{},"quantity":1,"price":850,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":850,"total_with_tax":850,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":850,"total_with_tax":850,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":850,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":0,"total_due":850,"paid_in_full":false,"furs":null,"fina":null},"description":"invoice with customer response"},"With referenced customer":{"value":{"id":"inv_6595a27b5d35015c3ef0c401","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00004","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":"cus_6595a27b5d35015c3ef0c3fd","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","country":"US"},"items":[{"id":"inv_item_6595a27b5d35015c3ef0c401","invoice_id":"inv_6595a27b5d35015c3ef0c401","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":null,"translations":{},"quantity":1,"price":5000,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":5000,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":5000,"total_with_tax":5000,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":5000,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":0,"total_due":5000,"paid_in_full":false,"furs":null,"fina":null},"description":"invoice with referenced customer response"},"With tax":{"value":{"id":"inv_6595a27b5d35015c3ef0c3ff","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00003","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"id":"inv_item_6595a27b5d35015c3ef0c3ff","invoice_id":"inv_6595a27b5d35015c3ef0c3ff","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"EVA Toolkit - Standard","description":null,"translations":{},"quantity":8,"price":150,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"},{"id":"inv_item_6595a27b5d35015c3ef0c400","invoice_id":"inv_6595a27b5d35015c3ef0c3ff","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":null,"translations":{},"quantity":10,"price":120,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":2400,"total_with_tax":2928,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":2400,"rate":22,"amount":528,"reverse_charge":false,"tax_id":null}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":0,"total_due":2928,"paid_in_full":false,"furs":null,"fina":null},"description":"invoice with tax calculations response"},"With partial payment":{"value":{"id":"inv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"inv_item_6595a27b5d35015c3ef0c3fd","invoice_id":"inv_6595a27b5d35015c3ef0c3fd","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":500,"total_due":1000,"paid_in_full":false,"furs":null,"fina":null,"payments":[{"id":"pmt_6595a27b5d35015c3ef0c3fd","invoice_id":"inv_6595a27b5d35015c3ef0c3fd","credit_note_id":null,"advance_invoice_id":null,"entity_id":"ent_6595a27b5d35015c3ef0c3fd","amount":500,"type":"cash","date":"2026-01-01T00:00:00.000Z","reference":null,"note":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}]},"description":"Invoice created with partial payment - balance due"},"With payment":{"value":{"id":"inv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"inv_item_6595a27b5d35015c3ef0c3fd","invoice_id":"inv_6595a27b5d35015c3ef0c3fd","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":1500,"total_due":0,"paid_in_full":true,"furs":null,"fina":null,"payments":[{"id":"pmt_6595a27b5d35015c3ef0c3fd","invoice_id":"inv_6595a27b5d35015c3ef0c3fd","credit_note_id":null,"advance_invoice_id":null,"entity_id":"ent_6595a27b5d35015c3ef0c3fd","amount":1500,"type":"bank_transfer","date":"2026-01-01T00:00:00.000Z","reference":null,"note":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}]},"description":"Invoice created with payment - paid in full"},"Complete":{"value":{"id":"inv_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"inv_item_6595a27b5d35015c3ef0c402","invoice_id":"inv_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"inv_item_6595a27b5d35015c3ef0c403","invoice_id":"inv_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2025-04-15T00:00:00.000Z","total_paid":0,"total_due":36600,"paid_in_full":false,"furs":null,"fina":null},"description":"Complete invoice response with all fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getInvoices","summary":"List all invoices","description":"Retrieve a paginated list of invoices with optional filtering and sorting.\nSupports cursor-based pagination, flexible JSON querying with MongoDB-style operators, full-text search, and sorting.","security":[{"Bearer":[]}],"tags":["Invoices"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","number","date","total","total_with_tax","created_at","updated_at","date_due","total_due","-id","-number","-date","-total","-total_with_tax","-created_at","-updated_at","-date_due","-total_due"]},{"type":"array","items":{"type":"string","enum":["id","number","date","total","total_with_tax","created_at","updated_at","date_due","total_due","-id","-number","-date","-total","-total_with_tax","-created_at","-updated_at","-date_due","-total_due"]}}],"description":"Sort invoices by one field or provide a repeated array for multi-column ordering. Use `total_due` for the smallest outstanding amount first or `-total_due` for the largest outstanding amount first. Prefix any supported field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort invoices by one field or provide a repeated array for multi-column ordering. Use `total_due` for the smallest outstanding amount first or `-total_due` for the largest outstanding amount first. Prefix any supported field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at, date_due, paid_in_full, total_due, total_paid, voided_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at, date_due, paid_in_full, total_due, total_paid, voided_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"type":"string","description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","example":"Acme Corporation"},"required":false,"description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","name":"search","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `payments` - Payment records linked to this invoice\n- `document_relations` - Linked documents (credit notes, advance invoices, etc.)\n\n**Usage:**\n`?include=payments`\n`?include=payments,document_relations`","example":"payments"},"required":false,"description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `payments` - Payment records linked to this invoice\n- `document_relations` - Linked documents (credit notes, advance invoices, etc.)\n\n**Usage:**\n`?include=payments`\n`?include=payments,document_relations`","name":"include","in":"query"},{"schema":{"type":"boolean","description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items."},"required":false,"description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.","name":"deleted","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of Invoices","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceList"},"examples":{"200":{"value":{"data":[{"id":"inv_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"inv_item_6595a27b5d35015c3ef0c402","invoice_id":"inv_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"inv_item_6595a27b5d35015c3ef0c403","invoice_id":"inv_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2025-04-15T00:00:00.000Z","total_paid":0,"total_due":36600,"paid_in_full":false,"furs":null,"fina":null}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of invoices"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/custom":{"post":{"operationId":"createCustomInvoice","summary":"Create invoice with pre-calculated totals","description":"Advanced endpoint for importing invoices that already have authoritative pre-calculated totals. Do not use this for normal invoice creation. Prefer the standard create endpoint unless your integration must preserve exact external totals from an ERP, OCR, migration, or accounting system.\nThe caller provides `total`, `total_with_tax`, `total_discount`, and `taxes` at the document level, and `total`/`total_with_tax` on each line item.\nWhen `calculation_mode` is omitted, Space Invoices preserves pass-through behavior and accepts the supplied totals as-is.\nWhen `calculation_mode` is provided, Space Invoices validates the supplied totals against that calculation mode before creating the document.\nAll other logic (numbering, fiscalization, customer handling, payments, lifecycle hooks) is identical to the standard create endpoint.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Invoices"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"description":"Custom Invoice Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomCreateInvoice"},"examples":{"Custom with totals":{"value":{"total":1500,"total_with_tax":1830,"taxes":[{"rate":22,"base":1500,"amount":330}],"items":[{"name":"Imported Service","quantity":1,"price":1500,"total":1500,"total_with_tax":1830,"taxes":[{"rate":22}]}]},"description":"Custom invoice with pre-calculated totals from external ERP system"}}}}},"responses":{"201":{"description":"Created Invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"},"examples":{"Minimal":{"value":{"id":"inv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"inv_item_6595a27b5d35015c3ef0c3fd","invoice_id":"inv_6595a27b5d35015c3ef0c3fd","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":0,"total_due":1500,"paid_in_full":false,"furs":null,"fina":null},"description":"Minimal invoice response"},"With customer":{"value":{"id":"inv_6595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00002","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Nebula Propulsion Labs"},"items":[{"id":"inv_item_6595a27b5d35015c3ef0c3fe","invoice_id":"inv_6595a27b5d35015c3ef0c3fe","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Thermal Shielding Panel","description":null,"translations":{},"quantity":1,"price":850,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":850,"total_with_tax":850,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":850,"total_with_tax":850,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":850,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":0,"total_due":850,"paid_in_full":false,"furs":null,"fina":null},"description":"invoice with customer response"},"With referenced customer":{"value":{"id":"inv_6595a27b5d35015c3ef0c401","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00004","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":"cus_6595a27b5d35015c3ef0c3fd","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","country":"US"},"items":[{"id":"inv_item_6595a27b5d35015c3ef0c401","invoice_id":"inv_6595a27b5d35015c3ef0c401","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":null,"translations":{},"quantity":1,"price":5000,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":5000,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":5000,"total_with_tax":5000,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":5000,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":0,"total_due":5000,"paid_in_full":false,"furs":null,"fina":null},"description":"invoice with referenced customer response"},"With tax":{"value":{"id":"inv_6595a27b5d35015c3ef0c3ff","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00003","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"id":"inv_item_6595a27b5d35015c3ef0c3ff","invoice_id":"inv_6595a27b5d35015c3ef0c3ff","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"EVA Toolkit - Standard","description":null,"translations":{},"quantity":8,"price":150,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"},{"id":"inv_item_6595a27b5d35015c3ef0c400","invoice_id":"inv_6595a27b5d35015c3ef0c3ff","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":null,"translations":{},"quantity":10,"price":120,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":2400,"total_with_tax":2928,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":2400,"rate":22,"amount":528,"reverse_charge":false,"tax_id":null}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":0,"total_due":2928,"paid_in_full":false,"furs":null,"fina":null},"description":"invoice with tax calculations response"},"With partial payment":{"value":{"id":"inv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"inv_item_6595a27b5d35015c3ef0c3fd","invoice_id":"inv_6595a27b5d35015c3ef0c3fd","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":500,"total_due":1000,"paid_in_full":false,"furs":null,"fina":null,"payments":[{"id":"pmt_6595a27b5d35015c3ef0c3fd","invoice_id":"inv_6595a27b5d35015c3ef0c3fd","credit_note_id":null,"advance_invoice_id":null,"entity_id":"ent_6595a27b5d35015c3ef0c3fd","amount":500,"type":"cash","date":"2026-01-01T00:00:00.000Z","reference":null,"note":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}]},"description":"Invoice created with partial payment - balance due"},"With payment":{"value":{"id":"inv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"inv_item_6595a27b5d35015c3ef0c3fd","invoice_id":"inv_6595a27b5d35015c3ef0c3fd","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":1500,"total_due":0,"paid_in_full":true,"furs":null,"fina":null,"payments":[{"id":"pmt_6595a27b5d35015c3ef0c3fd","invoice_id":"inv_6595a27b5d35015c3ef0c3fd","credit_note_id":null,"advance_invoice_id":null,"entity_id":"ent_6595a27b5d35015c3ef0c3fd","amount":1500,"type":"bank_transfer","date":"2026-01-01T00:00:00.000Z","reference":null,"note":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}]},"description":"Invoice created with payment - paid in full"},"Complete":{"value":{"id":"inv_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"inv_item_6595a27b5d35015c3ef0c402","invoice_id":"inv_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"inv_item_6595a27b5d35015c3ef0c403","invoice_id":"inv_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2025-04-15T00:00:00.000Z","total_paid":0,"total_due":36600,"paid_in_full":false,"furs":null,"fina":null},"description":"Complete invoice response with all fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}":{"get":{"operationId":"getInvoiceById","summary":"Get invoice by ID","description":"Retrieve a single invoice by its unique identifier. Returns the complete invoice details including all line items, customer information, and calculated totals.","security":[{"Bearer":[]}],"tags":["Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `payments` - Payment records linked to this invoice\n- `document_relations` - Linked documents (credit notes, advance invoices, etc.)\n\n**Usage:**\n`?include=payments`\n`?include=payments,document_relations`","example":"payments"},"required":false,"description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `payments` - Payment records linked to this invoice\n- `document_relations` - Linked documents (credit notes, advance invoices, etc.)\n\n**Usage:**\n`?include=payments`\n`?include=payments,document_relations`","name":"include","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Invoice instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"},"examples":{"200":{"value":{"id":"inv_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"inv_item_6595a27b5d35015c3ef0c402","invoice_id":"inv_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"inv_item_6595a27b5d35015c3ef0c403","invoice_id":"inv_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2025-04-15T00:00:00.000Z","total_paid":0,"total_due":36600,"paid_in_full":false,"furs":null,"fina":null},"description":"Complete invoice response with all fields"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateInvoice","summary":"Update an invoice","description":"Update an existing invoice.\nCreates a version snapshot before applying changes.\nCannot update voided or FURS-fiscalized invoices.\nIf items are provided, they replace all existing items.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Invoice Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInvoice"},"examples":{"Update note":{"value":{"note":"Payment received. Thank you!","change_reason":"Added thank you note after payment"},"description":"Update only the note field"},"Update items":{"value":{"items":[{"name":"Mission Planning Services","quantity":40,"price":125},{"name":"Telemetry platform hosting","quantity":1,"price":500}],"change_reason":"Corrected hours billed"},"description":"Replace all items (recalculates totals)"}}}}},"responses":{"200":{"description":"Updated Invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"},"examples":{"200":{"value":{"id":"inv_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"inv_item_6595a27b5d35015c3ef0c402","invoice_id":"inv_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"inv_item_6595a27b5d35015c3ef0c403","invoice_id":"inv_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2025-04-15T00:00:00.000Z","total_paid":0,"total_due":36600,"paid_in_full":false,"furs":null,"fina":null},"description":"Complete invoice response with all fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/xrechnung":{"get":{"operationId":"downloadInvoiceXRechnung","summary":"Download invoice as XRechnung XML","description":"Download a finalized German invoice as XRechnung XML. Requires a German entity with XRechnung enabled and a current valid XRechnung validation state.","security":[{"Bearer":[]}],"tags":["Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"XRechnung XML document","content":{"application/xml":{"schema":{"type":"string","description":"XRechnung XML document"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/zugferd":{"get":{"operationId":"downloadInvoiceZugferd","summary":"Download invoice as ZUGFeRD PDF","description":"Download a finalized German invoice as a ZUGFeRD/Factur-X PDF with embedded CII XML. Requires a German entity with ZUGFeRD enabled and a current valid ZUGFeRD validation state.","security":[{"Bearer":[]}],"tags":["Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"ZUGFeRD PDF document","content":{"application/pdf":{"schema":{"type":"string","format":"binary","description":"ZUGFeRD PDF document binary"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/versions":{"get":{"operationId":"getInvoiceVersions","summary":"Get invoice version history","description":"Retrieve the version history for an invoice. Each version represents the document state before an update was applied.","security":[{"Bearer":[]}],"tags":["Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Invoice version history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentVersionList"},"examples":{"200":{"value":{"versions":[{"id":"ver_abc123","document_type":"invoice","document_id":"inv_6595a27b5d35015c3ef0c3fd","version":2,"snapshot":{"id":"inv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"inv_item_6595a27b5d35015c3ef0c3fd","invoice_id":"inv_6595a27b5d35015c3ef0c3fd","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":0,"total_due":1500,"paid_in_full":false,"furs":null,"fina":null},"changed_fields":["note"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Added payment confirmation","created_at":"2025-01-15T10:30:00.000Z"},{"id":"ver_xyz789","document_type":"invoice","document_id":"inv_6595a27b5d35015c3ef0c3fd","version":1,"snapshot":{"id":"inv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"inv_item_6595a27b5d35015c3ef0c3fd","invoice_id":"inv_6595a27b5d35015c3ef0c3fd","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":0,"total_due":1500,"paid_in_full":false,"furs":null,"fina":null},"changed_fields":["items"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Corrected line items","created_at":"2025-01-14T15:00:00.000Z"}],"count":2},"description":"Version history with 2 updates"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/versions/{version}":{"get":{"operationId":"getInvoiceVersion","summary":"Get specific invoice version","description":"Retrieve a specific version snapshot of an invoice.","security":[{"Bearer":[]}],"tags":["Invoices"],"parameters":[{"schema":{"type":"string","description":"Invoice ID"},"required":true,"description":"Invoice ID","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"description":"Version number"},"required":true,"description":"Version number","name":"version","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Invoice version snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentVersion"},"examples":{"200":{"value":{"id":"ver_abc123","document_type":"invoice","document_id":"inv_6595a27b5d35015c3ef0c3fd","version":1,"snapshot":{"id":"inv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"inv_item_6595a27b5d35015c3ef0c3fd","invoice_id":"inv_6595a27b5d35015c3ef0c3fd","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_due":"2026-02-01T00:00:00.000Z","total_paid":0,"total_due":1500,"paid_in_full":false,"furs":null,"fina":null},"changed_fields":["items"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Corrected line items","created_at":"2025-01-14T15:00:00.000Z"},"description":"Single version snapshot"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/render":{"post":{"operationId":"renderInvoicePreview","summary":"Render invoice preview","description":"Render an HTML preview of an invoice without saving to the database. Perfect for displaying live previews in invoice creation/edit forms. Supports both partial mode (allows incomplete data for drafts) and complete mode (validates all required fields).","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Invoices"],"parameters":[{"schema":{"type":"string","enum":["modern","classic","condensed","minimal","fashion"],"description":"Document template design to use. When not specified, uses the entity's configured template.","example":"modern"},"required":false,"description":"Document template design to use. When not specified, uses the entity's configured template.","name":"template","in":"query"},{"schema":{"type":["string","null"],"minLength":2,"maxLength":5,"description":"Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.","example":"sl-SI"},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.","name":"locale","in":"query"},{"schema":{"type":["string","null"],"minLength":2,"maxLength":5,"description":"Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.","example":"en-US"},"required":false,"description":"Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.","name":"language","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"true","description":"Whether to treat the document as partial (allows incomplete data) or complete (validates all required fields)","example":"true"},"required":false,"description":"Whether to treat the document as partial (allows incomplete data) or complete (validates all required fields)","name":"partial","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override UPN QR enabled setting for preview"},"required":false,"description":"Override UPN QR enabled setting for preview","name":"upn_qr_enabled","in":"query"},{"schema":{"type":"string","enum":["qr_only","full_slip"],"description":"Override UPN QR display mode for preview"},"required":false,"description":"Override UPN QR display mode for preview","name":"upn_qr_display_mode","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override EPC QR enabled setting for preview"},"required":false,"description":"Override EPC QR enabled setting for preview","name":"epc_qr_enabled","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override Croatian HUB3 PDF417 barcode enabled setting for preview"},"required":false,"description":"Override Croatian HUB3 PDF417 barcode enabled setting for preview","name":"hub3_qr_enabled","in":"query"},{"schema":{"type":"string","minLength":4,"maxLength":4,"pattern":"^[A-Z]{4}$","description":"Override HUB3 purpose code for preview"},"required":false,"description":"Override HUB3 purpose code for preview","name":"hub3_qr_purpose_code","in":"query"},{"schema":{"type":"string","pattern":"^HR\\d{2}$","description":"Override HUB3 Croatian reference model for preview"},"required":false,"description":"Override HUB3 Croatian reference model for preview","name":"hub3_qr_reference_model","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Invoice Data","required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PartialInvoicePreview"},{"$ref":"#/components/schemas/CompleteInvoicePreview"}]},"examples":{"Partial":{"value":{"items":[{"name":"Consulting Services","quantity":5,"price":150}],"customer":{"name":"Acme Corp"}},"description":"Partial invoice render with minimal data"},"Complete":{"value":{"items":[{"name":"Consulting Services","quantity":5,"price":150,"taxes":[{"rate":22}]}],"customer":{"name":"Acme Corp","address":"123 Main St","city":"New York","post_code":"10001","country":"US"},"date":"2025-01-15","date_due":"2025-02-15"},"description":"Complete invoice render with full data"}}}}},"responses":{"200":{"description":"Rendered document (HTML)","content":{"text/html":{"schema":{"type":"string","description":"Fully formatted HTML document ready for display"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/void":{"post":{"operationId":"voidInvoice","summary":"Void an invoice","description":"Void an invoice for technical reasons (duplicate, error, etc.). For FURS-fiscalized invoices, automatically submits technical cancellation to FURS and creates a credit note. For business corrections, create a credit note instead.","tags":["Invoices"],"x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Void Invoice Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"description":"Technical reason for voiding (e.g., 'Duplicate invoice', 'Technical error')","example":"Duplicate invoice - issued in error"},"has_original_document":{"type":["boolean","null"],"description":"Whether the original physical/manual PT document is still available.","example":true}}},"examples":{"Void Invoice":{"value":{"reason":"Duplicate invoice created by mistake"}}}}}},"responses":{"200":{"description":"Voided Invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"},"examples":{"Voided Invoice":{"value":{"id":"inv_abc123","voided_at":"2026-01-20T12:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices/{id}/fiscalize":{"post":{"operationId":"fiscalizeInvoice","summary":"Fiscalize an old invoice (deprecated)","deprecated":true,"description":"Deprecated. Use POST /documents/{id}/fiscalize instead. Manually fiscalize an invoice that was created before FURS was enabled. Creates or reuses a dedicated \"OLD\" device under an existing active FURS premise, assigns a new sequential FURS number (Premise-OLD-N), and submits to FURS with SubsequentSubmit=true and SpecialNotes=#OLDINV;. The original invoice number remains unchanged.","tags":["Invoices"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Fiscalized Invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"},"examples":{"Fiscalized Invoice":{"value":{"id":"inv_abc123","furs":{"country_code":"SI","status":"success","fiscalized_at":"2026-01-20T12:00:00.000Z","data":{"zoi":"a1b2c3d4e5f6...","eor":"EOR-12345","business_premise_name":"P1","electronic_device_name":"OLD","invoice_number":"1"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/estimates/shareable/{shareableId}":{"get":{"operationId":"getShareableEstimate","summary":"View shareable estimate","description":"Retrieve estimate data using a shareable token. No authentication required. Returns full estimate data for rendering.","security":[],"tags":["Estimates"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"}],"responses":{"200":{"description":"Estimate data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Estimate"},"examples":{"200":{"value":{"id":"est_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"est_item_6595a27b5d35015c3ef0c402","estimate_id":"est_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"est_item_6595a27b5d35015c3ef0c403","estimate_id":"est_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2025-04-15T00:00:00.000Z"},"description":"Complete estimate response with all fields"}}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/estimates/shareable/{shareableId}/html":{"get":{"operationId":"getShareableEstimateHtml","summary":"Get shareable estimate as HTML","description":"Get estimate as HTML preview using a shareable token. No authentication required. Supports multiple languages via locale query parameter.","security":[],"tags":["Estimates"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale."},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale.","name":"locale","in":"query"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Language for document labels/translations. Defaults to locale value."},"required":false,"description":"Language for document labels/translations. Defaults to locale value.","name":"language","in":"query"}],"responses":{"200":{"description":"Rendered document (HTML)","content":{"text/html":{"schema":{"type":"string","description":"Fully formatted HTML document ready for display"}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/estimates/shareable/{shareableId}/pdf":{"get":{"operationId":"getShareableEstimatePdf","summary":"Download shareable estimate as PDF","description":"Download estimate as PDF using a shareable token. No authentication required. Supports multiple languages via locale query parameter.","security":[],"tags":["Estimates"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale."},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale.","name":"locale","in":"query"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Language for document labels/translations. Defaults to locale value."},"required":false,"description":"Language for document labels/translations. Defaults to locale value.","name":"language","in":"query"}],"responses":{"200":{"description":"PDF document","content":{"application/pdf":{"schema":{"type":"string","format":"binary","description":"PDF document binary"}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/estimates/shareable/{shareableId}/eslog":{"get":{"operationId":"getShareableEstimateEslog","summary":"Download shareable estimate as e-SLOG XML","description":"Download estimate as e-SLOG 2.0 XML (Slovenian electronic invoice format) using a shareable token. No authentication required. Only available for Slovenian entities with valid e-SLOG validation.","security":[],"tags":["Estimates"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"}],"responses":{"200":{"description":"e-SLOG XML document","content":{"application/xml":{"schema":{"type":"string","description":"e-SLOG 2.0 XML document"}}}},"404":{"description":"Invalid or expired shareable link, or document not valid for e-SLOG"}}}},"/estimates":{"post":{"operationId":"createEstimate","summary":"Create a new estimate","description":"Create a new estimate with line items.\nThis is the recommended endpoint for normal estimate creation. Use it when Space Invoices should calculate line totals, taxes, discounts, document totals, numbering, customer handling, and lifecycle hooks from the supplied business inputs.\nCustomer is optional - can be omitted or added inline without referencing a customer_id.\nThe estimate number is auto-generated based on the entity's number format settings.\nTaxes are calculated automatically based on the tax rates provided.\nEstimates are valid until the date_valid_till field (defaults to 30 days from creation).","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Estimates"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"description":"Create Estimate Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEstimate"},"examples":{"Minimal":{"value":{"items":[{"name":"Satellite Communication Module","quantity":1,"price":1500}]},"description":"Minimal document with single item, no customer, no taxes"},"With customer":{"value":{"customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Thermal Shielding Panel","quantity":1,"price":850}]},"description":"Document with inline customer (saved to database by default)"},"With referenced customer":{"value":{"customer_id":"cus_6595a27b5d35015c3ef0c3fd","items":[{"name":"Orbital Navigation License","quantity":1,"price":5000}]},"description":"Document referencing existing customer by ID"},"With tax":{"value":{"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"name":"EVA Toolkit - Standard","quantity":8,"price":150,"taxes":[{"rate":22}]},{"name":"Orbital Navigation License","quantity":10,"price":120,"taxes":[{"rate":22}]}]},"description":"Document with tax calculations (2 items, both with 22% VAT)"},"With tax classification":{"value":{"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"name":"Mission Control Console","quantity":8,"price":150,"taxes":[{"classification":"standard"}]},{"name":"Launch Safety Manual","quantity":5,"price":20,"taxes":[{"classification":"reduced"}]}]},"description":"Document using tax classification. Rate is resolved from entity's taxes by classification (e.g., \"standard\", \"reduced\", \"zero\"). Classification must exist on entity."},"With gross price":{"value":{"customer":{"name":"Orbital Systems GmbH"},"items":[{"name":"Ground Station Antenna Array","quantity":1,"gross_price":15250,"taxes":[{"rate":22}]}]},"description":"Document with gross pricing. Net price back-calculated: 15250 / 1.22 = 12500. Use gross prices for stable totals when VIES reverse charge may apply."},"With service period":{"value":{"date":"2025-03-01","date_service":"2025-03-01","date_service_to":"2025-03-31","customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Telemetry platform hosting","quantity":1,"price":1200}]},"description":"Document with a service period. Use date_service/date_service_to for subscriptions, retainers, and revenue recognition periods."},"With line discounts":{"value":{"calculation_mode":"b2b_standard","customer":{"name":"Horizon Launch Systems Inc."},"items":[{"name":"Mission planning package","quantity":1,"price":2000,"discounts":[{"type":"percent","value":10}],"taxes":[{"rate":22}]},{"name":"Launch readiness review","quantity":1,"price":500,"discounts":[{"type":"amount","value":50}],"taxes":[{"rate":22}]}]},"description":"Document with percentage and fixed line discounts. Discounts are applied per line before tax in b2b_standard mode."},"With financial categories":{"value":{"customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Ground Segment Implementation","quantity":1,"price":2500,"financial_category_id":"fcat_services"},{"name":"Telemetry platform hosting","quantity":1,"price":300,"financial_category_id":"fcat_hosting"}]},"description":"Document with per-line financial categories for revenue-by-category reporting. Use category_assignments when assigning by request item index instead."},"With category assignments":{"value":{"customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Ground Segment Implementation","quantity":1,"price":2500},{"name":"Telemetry platform hosting","quantity":1,"price":300}],"category_assignments":[{"item_index":0,"financial_category_id":"fcat_services"},{"item_index":1,"financial_category_id":"fcat_hosting"}]},"description":"Document with category assignments by line index. This is useful when item payloads come from an external system and categories are mapped separately."},"With rounding correction":{"value":{"customer":{"name":"Legacy Payload Systems Ltd."},"expected_total_with_tax":122.01,"items":[{"name":"Imported service line","quantity":1,"price":100,"taxes":[{"rate":22}]}]},"description":"Document with expected_total_with_tax for small external rounding differences. The API calculates a rounding correction within the allowed tolerance."},"With item prefill":{"value":{"customer":{"name":"Nebula Propulsion Labs"},"items":[{"item_id":"item_6595a27b5d35015c3ef0c3fd","quantity":5}]},"description":"Document with item prefilled from catalog. Name, price, and taxes are loaded from the catalog item. Only quantity needs to be specified."},"With item prefill and overrides":{"value":{"customer":{"name":"Alex Carter"},"items":[{"item_id":"item_6595a27b5d35015c3ef0c3fd","quantity":10,"price":1400,"description":"Bulk order discount applied"},{"item_id":"item_6595a27b5d35015c3ef0c3fe","quantity":2}]},"description":"Document with multiple catalog items. First item overrides price and description from catalog. Request values always take precedence over catalog values."},"With translations":{"value":{"items":[{"name":"Satellite Communication Module","quantity":1,"price":1500,"translations":{"name":{"de-DE":"Satelliten-Kommunikationsmodul"},"description":{"de-DE":"Hochleistungs-Kommunikationsmodul fuer den Orbitaleinsatz"}}}],"note":"Thank you for your business.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."}}},"description":"Minimal document with translated document and line-item content"},"As proforma invoice":{"value":{"customer":{"name":"Nebula Propulsion Labs"},"title_type":"proforma_invoice","date_valid_till":"2025-04-15","items":[{"name":"Ground Segment Implementation","quantity":1,"price":2500}]},"description":"Create an estimate that renders and behaves as a proforma invoice."},"Complete":{"value":{"date":"2025-03-15","note":"Thank you for your order. Equipment ships within 5 business days.","reference":"PO-2025-001","currency_code":"USD","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"items":[{"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"taxes":[{"rate":22}],"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"}},{"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"taxes":[{"rate":22}],"metadata":{"license_type":"enterprise","seats":"50"}}],"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"date_valid_till":"2025-04-15"},"description":"Complete document with all optional fields populated"}}}}},"responses":{"201":{"description":"Created Estimate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Estimate"},"examples":{"Minimal":{"value":{"id":"est_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"est_item_6595a27b5d35015c3ef0c3fd","estimate_id":"est_6595a27b5d35015c3ef0c3fd","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2026-02-01T00:00:00.000Z"},"description":"Minimal estimate response"},"With customer":{"value":{"id":"est_6595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00002","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Nebula Propulsion Labs"},"items":[{"id":"est_item_6595a27b5d35015c3ef0c3fe","estimate_id":"est_6595a27b5d35015c3ef0c3fe","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Thermal Shielding Panel","description":null,"translations":{},"quantity":1,"price":850,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":850,"total_with_tax":850,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":850,"total_with_tax":850,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":850,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2026-02-01T00:00:00.000Z"},"description":"estimate with customer response"},"With referenced customer":{"value":{"id":"est_6595a27b5d35015c3ef0c401","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00004","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":"cus_6595a27b5d35015c3ef0c3fd","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","country":"US"},"items":[{"id":"est_item_6595a27b5d35015c3ef0c401","estimate_id":"est_6595a27b5d35015c3ef0c401","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":null,"translations":{},"quantity":1,"price":5000,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":5000,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":5000,"total_with_tax":5000,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":5000,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2026-02-01T00:00:00.000Z"},"description":"estimate with referenced customer response"},"With tax":{"value":{"id":"est_6595a27b5d35015c3ef0c3ff","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00003","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"id":"est_item_6595a27b5d35015c3ef0c3ff","estimate_id":"est_6595a27b5d35015c3ef0c3ff","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"EVA Toolkit - Standard","description":null,"translations":{},"quantity":8,"price":150,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"},{"id":"est_item_6595a27b5d35015c3ef0c400","estimate_id":"est_6595a27b5d35015c3ef0c3ff","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":null,"translations":{},"quantity":10,"price":120,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":2400,"total_with_tax":2928,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":2400,"rate":22,"amount":528,"reverse_charge":false,"tax_id":null}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2026-02-01T00:00:00.000Z"},"description":"estimate with tax calculations response"},"Complete":{"value":{"id":"est_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"est_item_6595a27b5d35015c3ef0c402","estimate_id":"est_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"est_item_6595a27b5d35015c3ef0c403","estimate_id":"est_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2025-04-15T00:00:00.000Z"},"description":"Complete estimate response with all fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getEstimates","summary":"List all estimates","description":"Retrieve a paginated list of estimates with optional filtering and sorting.\nSupports cursor-based pagination, flexible JSON querying with MongoDB-style operators, full-text search, and sorting.","security":[{"Bearer":[]}],"tags":["Estimates"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","number","date","total","total_with_tax","created_at","updated_at","date_valid_till","-id","-number","-date","-total","-total_with_tax","-created_at","-updated_at","-date_valid_till"]},{"type":"array","items":{"type":"string","enum":["id","number","date","total","total_with_tax","created_at","updated_at","date_valid_till","-id","-number","-date","-total","-total_with_tax","-created_at","-updated_at","-date_valid_till"]}}],"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at, date_valid_till\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at, date_valid_till\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"type":"string","description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","example":"Acme Corporation"},"required":false,"description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","name":"search","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `document_relations` - Linked documents (invoices, etc.)\n\n**Usage:**\n`?include=document_relations`","example":"document_relations"},"required":false,"description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `document_relations` - Linked documents (invoices, etc.)\n\n**Usage:**\n`?include=document_relations`","name":"include","in":"query"},{"schema":{"type":"boolean","description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items."},"required":false,"description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.","name":"deleted","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of Estimates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateList"},"examples":{"200":{"value":{"data":[{"id":"est_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"est_item_6595a27b5d35015c3ef0c402","estimate_id":"est_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"est_item_6595a27b5d35015c3ef0c403","estimate_id":"est_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2025-04-15T00:00:00.000Z"}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of estimates"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/estimates/custom":{"post":{"operationId":"createCustomEstimate","summary":"Create estimate with pre-calculated totals","description":"Advanced endpoint for importing estimates that already have authoritative pre-calculated totals. Do not use this for normal estimate creation. Prefer the standard create endpoint unless your integration must preserve exact external totals from an ERP, OCR, migration, or accounting system.\nThe caller provides `total`, `total_with_tax`, `total_discount`, and `taxes` at the document level, and `total`/`total_with_tax` on each line item.\nWhen `calculation_mode` is omitted, Space Invoices preserves pass-through behavior and accepts the supplied totals as-is.\nWhen `calculation_mode` is provided, Space Invoices validates the supplied totals against that calculation mode before creating the document.\nAll other logic (numbering, customer handling, lifecycle hooks) is identical to the standard create endpoint.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Estimates"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"description":"Custom Estimate Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomCreateEstimate"},"examples":{"Custom with totals":{"value":{"total":5000,"total_with_tax":6100,"taxes":[{"rate":22,"base":5000,"amount":1100}],"items":[{"name":"Website Redesign","quantity":1,"price":5000,"total":5000,"total_with_tax":6100,"taxes":[{"rate":22}]}]},"description":"Custom estimate with pre-calculated totals from external system"}}}}},"responses":{"201":{"description":"Created Estimate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Estimate"},"examples":{"Minimal":{"value":{"id":"est_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"est_item_6595a27b5d35015c3ef0c3fd","estimate_id":"est_6595a27b5d35015c3ef0c3fd","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2026-02-01T00:00:00.000Z"},"description":"Minimal estimate response"},"With customer":{"value":{"id":"est_6595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00002","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Nebula Propulsion Labs"},"items":[{"id":"est_item_6595a27b5d35015c3ef0c3fe","estimate_id":"est_6595a27b5d35015c3ef0c3fe","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Thermal Shielding Panel","description":null,"translations":{},"quantity":1,"price":850,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":850,"total_with_tax":850,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":850,"total_with_tax":850,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":850,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2026-02-01T00:00:00.000Z"},"description":"estimate with customer response"},"With referenced customer":{"value":{"id":"est_6595a27b5d35015c3ef0c401","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00004","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":"cus_6595a27b5d35015c3ef0c3fd","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","country":"US"},"items":[{"id":"est_item_6595a27b5d35015c3ef0c401","estimate_id":"est_6595a27b5d35015c3ef0c401","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":null,"translations":{},"quantity":1,"price":5000,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":5000,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":5000,"total_with_tax":5000,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":5000,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2026-02-01T00:00:00.000Z"},"description":"estimate with referenced customer response"},"With tax":{"value":{"id":"est_6595a27b5d35015c3ef0c3ff","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00003","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"id":"est_item_6595a27b5d35015c3ef0c3ff","estimate_id":"est_6595a27b5d35015c3ef0c3ff","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"EVA Toolkit - Standard","description":null,"translations":{},"quantity":8,"price":150,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"},{"id":"est_item_6595a27b5d35015c3ef0c400","estimate_id":"est_6595a27b5d35015c3ef0c3ff","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":null,"translations":{},"quantity":10,"price":120,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":2400,"total_with_tax":2928,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":2400,"rate":22,"amount":528,"reverse_charge":false,"tax_id":null}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2026-02-01T00:00:00.000Z"},"description":"estimate with tax calculations response"},"Complete":{"value":{"id":"est_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"est_item_6595a27b5d35015c3ef0c402","estimate_id":"est_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"est_item_6595a27b5d35015c3ef0c403","estimate_id":"est_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2025-04-15T00:00:00.000Z"},"description":"Complete estimate response with all fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/estimates/{id}":{"get":{"operationId":"getEstimateById","summary":"Get estimate by ID","description":"Retrieve a single estimate by its unique identifier. Returns the complete estimate details including all line items, customer information, and calculated totals.","security":[{"Bearer":[]}],"tags":["Estimates"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `document_relations` - Linked documents (invoices, etc.)\n\n**Usage:**\n`?include=document_relations`","example":"document_relations"},"required":false,"description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `document_relations` - Linked documents (invoices, etc.)\n\n**Usage:**\n`?include=document_relations`","name":"include","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Estimate instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Estimate"},"examples":{"200":{"value":{"id":"est_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"est_item_6595a27b5d35015c3ef0c402","estimate_id":"est_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"est_item_6595a27b5d35015c3ef0c403","estimate_id":"est_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2025-04-15T00:00:00.000Z"},"description":"Complete estimate response with all fields"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateEstimate","summary":"Update an estimate","description":"Update an existing estimate.\nCreates a version snapshot before applying changes.\nCannot update voided estimates.\nIf items are provided, they replace all existing items.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Estimates"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Estimate Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEstimate"},"examples":{"Update note":{"value":{"note":"Updated pricing valid until end of month","change_reason":"Added validity note"},"description":"Update only the note field"},"Update items":{"value":{"items":[{"name":"Mission Planning Services","quantity":40,"price":125},{"name":"Design Services","quantity":10,"price":100}],"change_reason":"Revised scope and pricing"},"description":"Replace all items (recalculates totals)"},"Update validity":{"value":{"date_valid_till":"2025-06-30","change_reason":"Extended validity period"},"description":"Update the estimate validity date"}}}}},"responses":{"200":{"description":"Updated Estimate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Estimate"},"examples":{"200":{"value":{"id":"est_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"est_item_6595a27b5d35015c3ef0c402","estimate_id":"est_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"est_item_6595a27b5d35015c3ef0c403","estimate_id":"est_6595a27b5d35015c3ef0c402","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2025-04-15T00:00:00.000Z"},"description":"Complete estimate response with all fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/estimates/{id}/versions":{"get":{"operationId":"getEstimateVersions","summary":"Get estimate version history","description":"Retrieve the version history for an estimate. Each version represents the document state before an update was applied.","security":[{"Bearer":[]}],"tags":["Estimates"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Estimate version history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentVersionList"},"examples":{"200":{"value":{"versions":[{"id":"ver_abc123","document_type":"estimate","document_id":"est_6595a27b5d35015c3ef0c3fd","version":2,"snapshot":{"id":"est_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"est_item_6595a27b5d35015c3ef0c3fd","estimate_id":"est_6595a27b5d35015c3ef0c3fd","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2026-02-01T00:00:00.000Z"},"changed_fields":["note"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Updated validity note","created_at":"2025-01-15T10:30:00.000Z"},{"id":"ver_xyz789","document_type":"estimate","document_id":"est_6595a27b5d35015c3ef0c3fd","version":1,"snapshot":{"id":"est_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"est_item_6595a27b5d35015c3ef0c3fd","estimate_id":"est_6595a27b5d35015c3ef0c3fd","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2026-02-01T00:00:00.000Z"},"changed_fields":["items"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Revised scope and pricing","created_at":"2025-01-14T15:00:00.000Z"}],"count":2},"description":"Version history with 2 updates"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/estimates/{id}/versions/{version}":{"get":{"operationId":"getEstimateVersion","summary":"Get specific estimate version","description":"Retrieve a specific version snapshot of an estimate.","security":[{"Bearer":[]}],"tags":["Estimates"],"parameters":[{"schema":{"type":"string","description":"Estimate ID"},"required":true,"description":"Estimate ID","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"description":"Version number"},"required":true,"description":"Version number","name":"version","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Estimate version snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentVersion"},"examples":{"200":{"value":{"id":"ver_abc123","document_type":"estimate","document_id":"est_6595a27b5d35015c3ef0c3fd","version":1,"snapshot":{"id":"est_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"est_item_6595a27b5d35015c3ef0c3fd","estimate_id":"est_6595a27b5d35015c3ef0c3fd","advance_invoice_id":null,"expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"date_valid_till":"2026-02-01T00:00:00.000Z"},"changed_fields":["items"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Revised scope and pricing","created_at":"2025-01-14T15:00:00.000Z"},"description":"Single version snapshot"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/estimates/render":{"post":{"operationId":"renderEstimatePreview","summary":"Render estimate preview","description":"Render an HTML preview of an estimate without saving to the database. Perfect for displaying live previews in estimate creation/edit forms. Supports both partial mode (allows incomplete data for drafts) and complete mode (validates all required fields).","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Estimates"],"parameters":[{"schema":{"type":"string","enum":["modern","classic","condensed","minimal","fashion"],"description":"Document template design to use. When not specified, uses the entity's configured template.","example":"modern"},"required":false,"description":"Document template design to use. When not specified, uses the entity's configured template.","name":"template","in":"query"},{"schema":{"type":["string","null"],"minLength":2,"maxLength":5,"description":"Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.","example":"sl-SI"},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.","name":"locale","in":"query"},{"schema":{"type":["string","null"],"minLength":2,"maxLength":5,"description":"Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.","example":"en-US"},"required":false,"description":"Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.","name":"language","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"true","description":"Whether to treat the document as partial (allows incomplete data) or complete (validates all required fields)","example":"true"},"required":false,"description":"Whether to treat the document as partial (allows incomplete data) or complete (validates all required fields)","name":"partial","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override UPN QR enabled setting for preview"},"required":false,"description":"Override UPN QR enabled setting for preview","name":"upn_qr_enabled","in":"query"},{"schema":{"type":"string","enum":["qr_only","full_slip"],"description":"Override UPN QR display mode for preview"},"required":false,"description":"Override UPN QR display mode for preview","name":"upn_qr_display_mode","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override EPC QR enabled setting for preview"},"required":false,"description":"Override EPC QR enabled setting for preview","name":"epc_qr_enabled","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override Croatian HUB3 PDF417 barcode enabled setting for preview"},"required":false,"description":"Override Croatian HUB3 PDF417 barcode enabled setting for preview","name":"hub3_qr_enabled","in":"query"},{"schema":{"type":"string","minLength":4,"maxLength":4,"pattern":"^[A-Z]{4}$","description":"Override HUB3 purpose code for preview"},"required":false,"description":"Override HUB3 purpose code for preview","name":"hub3_qr_purpose_code","in":"query"},{"schema":{"type":"string","pattern":"^HR\\d{2}$","description":"Override HUB3 Croatian reference model for preview"},"required":false,"description":"Override HUB3 Croatian reference model for preview","name":"hub3_qr_reference_model","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Estimate Data","required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PartialEstimatePreview"},{"$ref":"#/components/schemas/CompleteEstimatePreview"}]},"examples":{"Partial":{"value":{"items":[{"name":"Website Redesign","quantity":1,"price":5000}],"customer":{"name":"Acme Corp"}},"description":"Partial estimate render with minimal data"},"Complete":{"value":{"items":[{"name":"Website Redesign","quantity":1,"price":5000,"taxes":[{"rate":22}]}],"customer":{"name":"Acme Corp","address":"123 Main St","city":"New York","post_code":"10001","country":"US"},"date":"2025-01-15","date_valid_till":"2025-02-15"},"description":"Complete estimate render with full data"}}}}},"responses":{"200":{"description":"Rendered document (HTML)","content":{"text/html":{"schema":{"type":"string","description":"Fully formatted HTML document ready for display"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credit-notes/shareable/{shareableId}":{"get":{"operationId":"getShareableCreditNote","summary":"View shareable credit note","description":"Retrieve credit note data using a shareable token. No authentication required. Returns full credit note data for rendering.","security":[],"tags":["CreditNotes"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"}],"responses":{"200":{"description":"Credit note data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditNote"},"examples":{"200":{"value":{"id":"cre_jkl012","number":"CN-2025-0004","date":"2025-01-15T00:00:00.000Z","date_service":"2025-01-01","date_service_to":"2025-01-15","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":null,"customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","tax_number":"74-1234567"},"note":"Credit note for defective thermal panels and returned EVA toolkit.","total":3900,"total_with_tax":4758,"taxes":[{"rate":22,"total":858}],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":4758,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_jkl012_1","name":"Thermal Shielding Panel - Manufacturing defect","description":"Panels failed thermal cycling test at 1400C","quantity":2,"price":850,"gross_price":null,"total":1700,"total_with_tax":2074,"taxes":[{"rate":22,"tax_id":"tax_abc123"}],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_jkl012","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},{"id":"item_jkl012_2","name":"EVA Toolkit - Standard return","description":null,"quantity":1,"price":2200,"gross_price":null,"total":2200,"total_with_tax":2684,"taxes":[{"rate":22,"tax_id":"tax_abc123"}],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_jkl012","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},"description":"Complete credit note response"}}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/credit-notes/shareable/{shareableId}/html":{"get":{"operationId":"getShareableCreditNoteHtml","summary":"Get shareable credit note as HTML","description":"Get credit note as HTML preview using a shareable token. No authentication required. Supports multiple languages via locale query parameter.","security":[],"tags":["CreditNotes"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale."},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale.","name":"locale","in":"query"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Language for document labels/translations. Defaults to locale value."},"required":false,"description":"Language for document labels/translations. Defaults to locale value.","name":"language","in":"query"}],"responses":{"200":{"description":"Rendered document (HTML)","content":{"text/html":{"schema":{"type":"string","description":"Fully formatted HTML document ready for display"}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/credit-notes/shareable/{shareableId}/pdf":{"get":{"operationId":"getShareableCreditNotePdf","summary":"Download shareable credit note as PDF","description":"Download credit note as PDF using a shareable token. No authentication required. Supports multiple languages via locale query parameter.","security":[],"tags":["CreditNotes"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale."},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale.","name":"locale","in":"query"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Language for document labels/translations. Defaults to locale value."},"required":false,"description":"Language for document labels/translations. Defaults to locale value.","name":"language","in":"query"}],"responses":{"200":{"description":"PDF document","content":{"application/pdf":{"schema":{"type":"string","format":"binary","description":"PDF document binary"}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/credit-notes/shareable/{shareableId}/eslog":{"get":{"operationId":"getShareableCreditNoteEslog","summary":"Download shareable credit note as e-SLOG XML","description":"Download credit note as e-SLOG 2.0 XML (Slovenian electronic invoice format) using a shareable token. No authentication required. Only available for Slovenian entities with valid e-SLOG validation.","security":[],"tags":["CreditNotes"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"}],"responses":{"200":{"description":"e-SLOG XML document","content":{"application/xml":{"schema":{"type":"string","description":"e-SLOG 2.0 XML document"}}}},"404":{"description":"Invalid or expired shareable link, or document not valid for e-SLOG"}}}},"/credit-notes":{"post":{"operationId":"createCreditNote","summary":"Create a new credit note","description":"Create a new credit note with line items.\nThis is the recommended endpoint for normal credit note creation. Use it when Space Invoices should calculate line totals, taxes, discounts, document totals, numbering, fiscalization, customer handling, payments, and lifecycle hooks from the supplied business inputs.\nSend credit-note line quantities and prices as positive values. Space Invoices stores credit notes as positive amounts and applies the credit-note sign in display, reporting, and fiscalization where required.\nCustomer is optional - can be omitted for retail/convenience store sales where customer information isn't needed, or added inline without referencing a customer_id.\nThe credit note number is auto-generated based on the entity's number format settings.\nTaxes are calculated automatically based on the tax rates provided.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["CreditNotes"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"description":"Create Credit Note Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCreditNote"},"examples":{"Minimal":{"value":{"items":[{"name":"Thermal Shielding Panel - Defective return","quantity":1,"price":850}]},"description":"Minimal credit note with one item"},"With referenced customer":{"value":{"customer_id":"cust_abc123","items":[{"name":"EVA Toolkit - Standard return","quantity":1,"price":2200}]},"description":"Credit note referencing an existing customer"},"With tax":{"value":{"items":[{"name":"Thermal Shielding Panel - Manufacturing defect","quantity":2,"price":850,"taxes":[{"rate":22}]}]},"description":"Credit note with tax"},"With linked invoice":{"value":{"linked_documents":["inv_6595a27b5d35015c3ef0c3fd"],"items":[{"name":"Refund for returned equipment","quantity":1,"price":500,"taxes":[{"rate":22}]}]},"description":"Create a credit note for an invoice. If no payment is supplied, the credit is automatically applied to the linked invoice balance."},"Complete":{"value":{"customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","tax_number":"74-1234567"},"items":[{"name":"Thermal Shielding Panel - Manufacturing defect","description":"Panels failed thermal cycling test at 1400C","quantity":2,"price":850,"taxes":[{"rate":22}]},{"name":"EVA Toolkit - Standard return","quantity":1,"price":2200,"taxes":[{"rate":22}]}],"note":"Credit note for defective thermal panels and returned EVA toolkit.","date":"2025-01-15","date_service":"2025-01-01","date_service_to":"2025-01-15"},"description":"Complete credit note with all fields"}}}}},"responses":{"201":{"description":"Created Credit Note","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditNote"},"examples":{"Minimal":{"value":{"id":"cre_abc123","number":"CN-2025-0001","date":"2025-01-15T00:00:00.000Z","date_service":null,"date_service_to":null,"issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":null,"customer":null,"note":null,"total":850,"total_with_tax":850,"taxes":[],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":850,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_abc123","name":"Thermal Shielding Panel - Defective return","description":null,"quantity":1,"price":850,"gross_price":null,"total":850,"total_with_tax":850,"taxes":[],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_abc123","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},"description":"Minimal credit note response"},"With referenced customer":{"value":{"id":"cre_ghi789","number":"CN-2025-0003","date":"2025-01-15T00:00:00.000Z","date_service":null,"date_service_to":null,"issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":"cust_abc123","customer":{"name":"Nebula Propulsion Labs","address":"42 Thrust Ave"},"note":null,"total":2200,"total_with_tax":2200,"taxes":[],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":2200,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_ghi789","name":"EVA Toolkit - Standard return","description":null,"quantity":1,"price":2200,"gross_price":null,"total":2200,"total_with_tax":2200,"taxes":[],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_ghi789","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},"description":"Credit note with referenced customer response"},"With tax":{"value":{"id":"cre_def456","number":"CN-2025-0002","date":"2025-01-15T00:00:00.000Z","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":null,"customer":null,"note":null,"total":1700,"total_with_tax":2074,"taxes":[{"rate":22,"total":374}],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":2074,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_def456","name":"Thermal Shielding Panel - Manufacturing defect","description":null,"quantity":2,"price":850,"gross_price":null,"total":1700,"total_with_tax":2074,"taxes":[{"rate":22,"tax_id":"tax_abc123"}],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_def456","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},"description":"Credit note with tax response"},"Complete":{"value":{"id":"cre_jkl012","number":"CN-2025-0004","date":"2025-01-15T00:00:00.000Z","date_service":"2025-01-01","date_service_to":"2025-01-15","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":null,"customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","tax_number":"74-1234567"},"note":"Credit note for defective thermal panels and returned EVA toolkit.","total":3900,"total_with_tax":4758,"taxes":[{"rate":22,"total":858}],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":4758,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_jkl012_1","name":"Thermal Shielding Panel - Manufacturing defect","description":"Panels failed thermal cycling test at 1400C","quantity":2,"price":850,"gross_price":null,"total":1700,"total_with_tax":2074,"taxes":[{"rate":22,"tax_id":"tax_abc123"}],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_jkl012","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},{"id":"item_jkl012_2","name":"EVA Toolkit - Standard return","description":null,"quantity":1,"price":2200,"gross_price":null,"total":2200,"total_with_tax":2684,"taxes":[{"rate":22,"tax_id":"tax_abc123"}],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_jkl012","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},"description":"Complete credit note response"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getCreditNotes","summary":"List all credit notes","description":"Retrieve a paginated list of credit notes with optional filtering and sorting.\nSupports cursor-based pagination, flexible JSON querying with MongoDB-style operators, full-text search, and sorting.","security":[{"Bearer":[]}],"tags":["CreditNotes"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","number","date","total","total_with_tax","created_at","updated_at","-id","-number","-date","-total","-total_with_tax","-created_at","-updated_at"]},{"type":"array","items":{"type":"string","enum":["id","number","date","total","total_with_tax","created_at","updated_at","-id","-number","-date","-total","-total_with_tax","-created_at","-updated_at"]}}],"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at, total_paid\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at, total_paid\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"type":"string","description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","example":"Acme Corporation"},"required":false,"description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","name":"search","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `payments` - Payment records linked to this credit note\n- `document_relations` - Linked documents (invoices, advance invoices, etc.)\n\n**Usage:**\n`?include=payments`\n`?include=payments,document_relations`","example":"payments"},"required":false,"description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `payments` - Payment records linked to this credit note\n- `document_relations` - Linked documents (invoices, advance invoices, etc.)\n\n**Usage:**\n`?include=payments`\n`?include=payments,document_relations`","name":"include","in":"query"},{"schema":{"type":"boolean","description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items."},"required":false,"description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.","name":"deleted","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of Credit Notes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditNoteList"},"examples":{"default":{"value":{"data":[{"id":"cre_abc123","number":"CN-2025-0001","date":"2025-01-15T00:00:00.000Z","date_service":null,"date_service_to":null,"issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":null,"customer":null,"note":null,"total":850,"total_with_tax":850,"taxes":[],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":850,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_abc123","name":"Thermal Shielding Panel - Defective return","description":null,"quantity":1,"price":850,"gross_price":null,"total":850,"total_with_tax":850,"taxes":[],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_abc123","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"List of credit notes"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credit-notes/custom":{"post":{"operationId":"createCustomCreditNote","summary":"Create credit note with pre-calculated totals","description":"Advanced endpoint for importing credit notes that already have authoritative pre-calculated totals. Do not use this for normal credit note creation. Prefer the standard create endpoint unless your integration must preserve exact external totals from an ERP, OCR, migration, or accounting system.\nThe caller provides `total`, `total_with_tax`, `total_discount`, and `taxes` at the document level, and `total`/`total_with_tax` on each line item.\nWhen `calculation_mode` is omitted, Space Invoices preserves pass-through behavior and accepts the supplied totals as-is.\nWhen `calculation_mode` is provided, Space Invoices validates the supplied totals against that calculation mode before creating the document.\nAll other logic (numbering, fiscalization, customer handling, payments, lifecycle hooks) is identical to the standard create endpoint.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["CreditNotes"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"description":"Custom Credit Note Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomCreateCreditNote"},"examples":{"Custom with totals":{"value":{"total":850,"total_with_tax":1037,"taxes":[{"rate":22,"base":850,"amount":187}],"items":[{"name":"Thermal Shielding Panel - Defective return","quantity":1,"price":850,"total":850,"total_with_tax":1037,"taxes":[{"rate":22}]}]},"description":"Custom credit note with pre-calculated totals from external system"}}}}},"responses":{"201":{"description":"Created Credit Note","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditNote"},"examples":{"Minimal":{"value":{"id":"cre_abc123","number":"CN-2025-0001","date":"2025-01-15T00:00:00.000Z","date_service":null,"date_service_to":null,"issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":null,"customer":null,"note":null,"total":850,"total_with_tax":850,"taxes":[],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":850,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_abc123","name":"Thermal Shielding Panel - Defective return","description":null,"quantity":1,"price":850,"gross_price":null,"total":850,"total_with_tax":850,"taxes":[],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_abc123","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},"description":"Minimal credit note response"},"With referenced customer":{"value":{"id":"cre_ghi789","number":"CN-2025-0003","date":"2025-01-15T00:00:00.000Z","date_service":null,"date_service_to":null,"issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":"cust_abc123","customer":{"name":"Nebula Propulsion Labs","address":"42 Thrust Ave"},"note":null,"total":2200,"total_with_tax":2200,"taxes":[],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":2200,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_ghi789","name":"EVA Toolkit - Standard return","description":null,"quantity":1,"price":2200,"gross_price":null,"total":2200,"total_with_tax":2200,"taxes":[],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_ghi789","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},"description":"Credit note with referenced customer response"},"With tax":{"value":{"id":"cre_def456","number":"CN-2025-0002","date":"2025-01-15T00:00:00.000Z","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":null,"customer":null,"note":null,"total":1700,"total_with_tax":2074,"taxes":[{"rate":22,"total":374}],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":2074,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_def456","name":"Thermal Shielding Panel - Manufacturing defect","description":null,"quantity":2,"price":850,"gross_price":null,"total":1700,"total_with_tax":2074,"taxes":[{"rate":22,"tax_id":"tax_abc123"}],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_def456","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},"description":"Credit note with tax response"},"Complete":{"value":{"id":"cre_jkl012","number":"CN-2025-0004","date":"2025-01-15T00:00:00.000Z","date_service":"2025-01-01","date_service_to":"2025-01-15","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":null,"customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","tax_number":"74-1234567"},"note":"Credit note for defective thermal panels and returned EVA toolkit.","total":3900,"total_with_tax":4758,"taxes":[{"rate":22,"total":858}],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":4758,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_jkl012_1","name":"Thermal Shielding Panel - Manufacturing defect","description":"Panels failed thermal cycling test at 1400C","quantity":2,"price":850,"gross_price":null,"total":1700,"total_with_tax":2074,"taxes":[{"rate":22,"tax_id":"tax_abc123"}],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_jkl012","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},{"id":"item_jkl012_2","name":"EVA Toolkit - Standard return","description":null,"quantity":1,"price":2200,"gross_price":null,"total":2200,"total_with_tax":2684,"taxes":[{"rate":22,"tax_id":"tax_abc123"}],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_jkl012","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},"description":"Complete credit note response"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credit-notes/{id}":{"get":{"operationId":"getCreditNoteById","summary":"Get credit note by ID","description":"Retrieve a single credit note by its unique identifier. Returns the complete credit note details including all line items, customer information, and calculated totals.","security":[{"Bearer":[]}],"tags":["CreditNotes"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `payments` - Payment records linked to this credit note\n- `document_relations` - Linked documents (invoices, advance invoices, etc.)\n\n**Usage:**\n`?include=payments`\n`?include=payments,document_relations`","example":"payments"},"required":false,"description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `payments` - Payment records linked to this credit note\n- `document_relations` - Linked documents (invoices, advance invoices, etc.)\n\n**Usage:**\n`?include=payments`\n`?include=payments,document_relations`","name":"include","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Credit Note instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditNote"},"examples":{"default":{"value":{"id":"cre_abc123","number":"CN-2025-0001","date":"2025-01-15T00:00:00.000Z","date_service":null,"date_service_to":null,"issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":null,"customer":null,"note":null,"total":850,"total_with_tax":850,"taxes":[],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":850,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_abc123","name":"Thermal Shielding Panel - Defective return","description":null,"quantity":1,"price":850,"gross_price":null,"total":850,"total_with_tax":850,"taxes":[],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_abc123","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},"description":"Minimal credit note response"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateCreditNote","summary":"Update a credit note","description":"Update an existing credit note.\nCreates a version snapshot before applying changes.\nCannot update voided or FURS-fiscalized credit notes.\nIf items are provided, they replace all existing items.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["CreditNotes"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Credit Note Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCreditNote"},"examples":{"Update note":{"value":{"note":"Refund processed. Equipment returned to inventory.","change_reason":"Added confirmation note after refund"},"description":"Update only the note field"},"Update items":{"value":{"items":[{"name":"Thermal Shielding Panel - Corrected return","quantity":1,"price":850},{"name":"EVA Toolkit - Standard return","quantity":1,"price":2200}],"change_reason":"Corrected refund quantities"},"description":"Replace all items (recalculates totals)"}}}}},"responses":{"200":{"description":"Updated Credit Note","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditNote"},"examples":{"200":{"value":{"id":"cre_jkl012","number":"CN-2025-0004","date":"2025-01-15T00:00:00.000Z","date_service":"2025-01-01","date_service_to":"2025-01-15","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":null,"customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","tax_number":"74-1234567"},"note":"Credit note for defective thermal panels and returned EVA toolkit.","total":3900,"total_with_tax":4758,"taxes":[{"rate":22,"total":858}],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":4758,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_jkl012_1","name":"Thermal Shielding Panel - Manufacturing defect","description":"Panels failed thermal cycling test at 1400C","quantity":2,"price":850,"gross_price":null,"total":1700,"total_with_tax":2074,"taxes":[{"rate":22,"tax_id":"tax_abc123"}],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_jkl012","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},{"id":"item_jkl012_2","name":"EVA Toolkit - Standard return","description":null,"quantity":1,"price":2200,"gross_price":null,"total":2200,"total_with_tax":2684,"taxes":[{"rate":22,"tax_id":"tax_abc123"}],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_jkl012","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},"description":"Complete credit note response"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credit-notes/{id}/xrechnung":{"get":{"operationId":"downloadCreditNoteXRechnung","summary":"Download credit note as XRechnung XML","description":"Download a finalized German credit note as XRechnung XML. Requires a German entity with XRechnung enabled and a current valid XRechnung validation state.","security":[{"Bearer":[]}],"tags":["CreditNotes"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"XRechnung XML document","content":{"application/xml":{"schema":{"type":"string","description":"XRechnung XML document"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credit-notes/{id}/zugferd":{"get":{"operationId":"downloadCreditNoteZugferd","summary":"Download credit note as ZUGFeRD PDF","description":"Download a finalized German credit note as a ZUGFeRD/Factur-X PDF with embedded CII XML. Requires a German entity with ZUGFeRD enabled and a current valid ZUGFeRD validation state.","security":[{"Bearer":[]}],"tags":["CreditNotes"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"ZUGFeRD PDF document","content":{"application/pdf":{"schema":{"type":"string","format":"binary","description":"ZUGFeRD PDF document binary"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credit-notes/{id}/versions":{"get":{"operationId":"getCreditNoteVersions","summary":"Get credit note version history","description":"Retrieve the version history for a credit note. Each version represents the document state before an update was applied.","security":[{"Bearer":[]}],"tags":["CreditNotes"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Credit note version history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentVersionList"},"examples":{"200":{"value":{"versions":[{"id":"ver_abc123","document_type":"credit_note","document_id":"cre_6595a27b5d35015c3ef0c3fd","version":2,"snapshot":{"id":"cre_abc123","number":"CN-2025-0001","date":"2025-01-15T00:00:00.000Z","date_service":null,"date_service_to":null,"issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":null,"customer":null,"note":null,"total":850,"total_with_tax":850,"taxes":[],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":850,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_abc123","name":"Thermal Shielding Panel - Defective return","description":null,"quantity":1,"price":850,"gross_price":null,"total":850,"total_with_tax":850,"taxes":[],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_abc123","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},"changed_fields":["note"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Added confirmation note after refund","created_at":"2025-01-15T10:30:00.000Z"},{"id":"ver_xyz789","document_type":"credit_note","document_id":"cre_6595a27b5d35015c3ef0c3fd","version":1,"snapshot":{"id":"cre_abc123","number":"CN-2025-0001","date":"2025-01-15T00:00:00.000Z","date_service":null,"date_service_to":null,"issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":null,"customer":null,"note":null,"total":850,"total_with_tax":850,"taxes":[],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":850,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_abc123","name":"Thermal Shielding Panel - Defective return","description":null,"quantity":1,"price":850,"gross_price":null,"total":850,"total_with_tax":850,"taxes":[],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_abc123","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},"changed_fields":["items"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Corrected refund amounts","created_at":"2025-01-14T15:00:00.000Z"}],"count":2},"description":"Version history with 2 updates"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credit-notes/{id}/versions/{version}":{"get":{"operationId":"getCreditNoteVersion","summary":"Get specific credit note version","description":"Retrieve a specific version snapshot of a credit note.","security":[{"Bearer":[]}],"tags":["CreditNotes"],"parameters":[{"schema":{"type":"string","description":"Credit Note ID"},"required":true,"description":"Credit Note ID","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"description":"Version number"},"required":true,"description":"Version number","name":"version","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Credit note version snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentVersion"},"examples":{"200":{"value":{"id":"ver_abc123","document_type":"credit_note","document_id":"cre_6595a27b5d35015c3ef0c3fd","version":1,"snapshot":{"id":"cre_abc123","number":"CN-2025-0001","date":"2025-01-15T00:00:00.000Z","date_service":null,"date_service_to":null,"issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","country":"United States"},"customer_id":null,"customer":null,"note":null,"total":850,"total_with_tax":850,"taxes":[],"currency_code":"USD","entity_id":"ent_abc123","date_year":2025,"shareable_id":null,"voided_at":null,"deleted_at":null,"metadata":{},"exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"total_paid":0,"total_due":850,"paid_in_full":false,"furs":null,"fina":null,"payment_terms":null,"items":[{"id":"item_abc123","name":"Thermal Shielding Panel - Defective return","description":null,"quantity":1,"price":850,"gross_price":null,"total":850,"total_with_tax":850,"taxes":[],"discounts":[],"type":null,"unit":null,"credit_note_id":"cre_abc123","total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"}],"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z"},"changed_fields":["items"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Corrected refund amounts","created_at":"2025-01-14T15:00:00.000Z"},"description":"Single version snapshot"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credit-notes/render":{"post":{"operationId":"renderCreditNotePreview","summary":"Render credit note preview","description":"Render an HTML preview of a credit note without saving to the database. Perfect for displaying live previews in credit note creation/edit forms. Supports both partial mode (allows incomplete data for drafts) and complete mode (validates all required fields).","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["CreditNotes"],"parameters":[{"schema":{"type":"string","enum":["modern","classic","condensed","minimal","fashion"],"description":"Document template design to use. When not specified, uses the entity's configured template.","example":"modern"},"required":false,"description":"Document template design to use. When not specified, uses the entity's configured template.","name":"template","in":"query"},{"schema":{"type":["string","null"],"minLength":2,"maxLength":5,"description":"Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.","example":"sl-SI"},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.","name":"locale","in":"query"},{"schema":{"type":["string","null"],"minLength":2,"maxLength":5,"description":"Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.","example":"en-US"},"required":false,"description":"Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.","name":"language","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"true","description":"Whether to treat the document as partial (allows incomplete data) or complete (validates all required fields)","example":"true"},"required":false,"description":"Whether to treat the document as partial (allows incomplete data) or complete (validates all required fields)","name":"partial","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override UPN QR enabled setting for preview"},"required":false,"description":"Override UPN QR enabled setting for preview","name":"upn_qr_enabled","in":"query"},{"schema":{"type":"string","enum":["qr_only","full_slip"],"description":"Override UPN QR display mode for preview"},"required":false,"description":"Override UPN QR display mode for preview","name":"upn_qr_display_mode","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override EPC QR enabled setting for preview"},"required":false,"description":"Override EPC QR enabled setting for preview","name":"epc_qr_enabled","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override Croatian HUB3 PDF417 barcode enabled setting for preview"},"required":false,"description":"Override Croatian HUB3 PDF417 barcode enabled setting for preview","name":"hub3_qr_enabled","in":"query"},{"schema":{"type":"string","minLength":4,"maxLength":4,"pattern":"^[A-Z]{4}$","description":"Override HUB3 purpose code for preview"},"required":false,"description":"Override HUB3 purpose code for preview","name":"hub3_qr_purpose_code","in":"query"},{"schema":{"type":"string","pattern":"^HR\\d{2}$","description":"Override HUB3 Croatian reference model for preview"},"required":false,"description":"Override HUB3 Croatian reference model for preview","name":"hub3_qr_reference_model","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Credit Note Data","required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PartialCreditNotePreview"},{"$ref":"#/components/schemas/CompleteCreditNotePreview"}]},"examples":{"Partial":{"value":{"items":[{"name":"Refund - Consulting Services","quantity":1,"price":150}],"customer":{"name":"Acme Corp"}},"description":"Partial credit note render with minimal data"},"Complete":{"value":{"items":[{"name":"Refund - Consulting Services","quantity":1,"price":150,"taxes":[{"rate":22}]}],"customer":{"name":"Acme Corp","address":"123 Main St","city":"New York","post_code":"10001","country":"US"},"date":"2025-01-15"},"description":"Complete credit note render with full data"}}}}},"responses":{"200":{"description":"Rendered document (HTML)","content":{"text/html":{"schema":{"type":"string","description":"Fully formatted HTML document ready for display"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credit-notes/{id}/fiscalize":{"post":{"operationId":"fiscalizeCreditNote","summary":"Fiscalize an old credit note (deprecated)","deprecated":true,"description":"Deprecated. Use POST /documents/{id}/fiscalize instead. Manually fiscalize a credit note that was created before FURS was enabled. Creates or reuses a dedicated \"OLD\" device under an existing active FURS premise, assigns a new sequential FURS number (Premise-OLD-N), and submits to FURS with SubsequentSubmit=true and SpecialNotes=#OLDINV;. The original credit note number remains unchanged.","tags":["CreditNotes"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Fiscalized Credit Note","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditNote"},"examples":{"Fiscalized Credit Note":{"value":{"id":"cre_abc123","furs":{"country_code":"SI","status":"success","fiscalized_at":"2026-01-20T12:00:00.000Z","data":{"zoi":"a1b2c3d4e5f6...","eor":"EOR-12345","business_premise_name":"P1","electronic_device_name":"OLD","invoice_number":"1"}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credit-notes/{id}/void":{"post":{"operationId":"voidCreditNote","summary":"Void a credit note","description":"Void a credit note for technical reasons (duplicate, error, etc.). For FURS-fiscalized credit notes, automatically submits technical cancellation to FURS. All linked payments are soft-deleted, reversing their effect on invoice totals.","tags":["CreditNotes"],"x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Void Credit Note Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"description":"Technical reason for voiding (e.g., 'Duplicate credit note', 'Technical error')","example":"Duplicate credit note - issued in error"},"has_original_document":{"type":["boolean","null"],"description":"Whether the original physical/manual PT document is still available.","example":true}}},"examples":{"Void Credit Note":{"value":{"reason":"Duplicate credit note created by mistake"}}}}}},"responses":{"200":{"description":"Voided Credit Note","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditNote"},"examples":{"Voided Credit Note":{"value":{"id":"cn_abc123","voided_at":"2026-01-20T12:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/advance-invoices/shareable/{shareableId}":{"get":{"operationId":"getShareableAdvanceInvoice","summary":"View shareable advance invoice","description":"Retrieve advance invoice data using a shareable token. No authentication required. Returns full advance invoice data for rendering.","security":[],"tags":["Advance Invoices"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"}],"responses":{"200":{"description":"Advance invoice data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvanceInvoice"},"examples":{"200":{"value":{"id":"adv_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"adv_item_6595a27b5d35015c3ef0c402","advance_invoice_id":"adv_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"adv_item_6595a27b5d35015c3ef0c403","advance_invoice_id":"adv_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":0,"total_due":10370,"paid_in_full":false,"furs":null,"fina":null},"description":"Complete advance_invoice response with all fields"}}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/advance-invoices/shareable/{shareableId}/html":{"get":{"operationId":"getShareableAdvanceInvoiceHtml","summary":"Get shareable advance invoice as HTML","description":"Get advance invoice as HTML preview using a shareable token. No authentication required. Supports multiple languages via locale query parameter.","security":[],"tags":["Advance Invoices"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale."},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale.","name":"locale","in":"query"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Language for document labels/translations. Defaults to locale value."},"required":false,"description":"Language for document labels/translations. Defaults to locale value.","name":"language","in":"query"}],"responses":{"200":{"description":"Rendered document (HTML)","content":{"text/html":{"schema":{"type":"string","description":"Fully formatted HTML document ready for display"}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/advance-invoices/shareable/{shareableId}/pdf":{"get":{"operationId":"getShareableAdvanceInvoicePdf","summary":"Download shareable advance invoice as PDF","description":"Download advance invoice as PDF using a shareable token. No authentication required. Supports multiple languages via locale query parameter.","security":[],"tags":["Advance Invoices"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale."},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale.","name":"locale","in":"query"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Language for document labels/translations. Defaults to locale value."},"required":false,"description":"Language for document labels/translations. Defaults to locale value.","name":"language","in":"query"}],"responses":{"200":{"description":"PDF document","content":{"application/pdf":{"schema":{"type":"string","format":"binary","description":"PDF document binary"}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/advance-invoices/shareable/{shareableId}/eslog":{"get":{"operationId":"getShareableAdvanceInvoiceEslog","summary":"Download shareable advance invoice as e-SLOG XML","description":"Download advance invoice as e-SLOG 2.0 XML (Slovenian electronic invoice format) using a shareable token. No authentication required. Only available for Slovenian entities with valid e-SLOG validation.","security":[],"tags":["Advance Invoices"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"}],"responses":{"200":{"description":"e-SLOG XML document","content":{"application/xml":{"schema":{"type":"string","description":"e-SLOG 2.0 XML document"}}}},"404":{"description":"Invalid or expired shareable link, or document not valid for e-SLOG"}}}},"/advance-invoices":{"post":{"operationId":"createAdvanceInvoice","summary":"Create a new advance invoice","description":"Create a new advance invoice with line items.\nThis is the recommended endpoint for normal advance invoice creation. Use it when Space Invoices should calculate line totals, taxes, discounts, document totals, numbering, fiscalization, customer handling, payments, and lifecycle hooks from the supplied business inputs.\nAdvance invoices are issued before goods/services are delivered to collect prepayment. When payment is received, the advance can be linked to a final invoice to apply the prepaid amount.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Advance Invoices"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"description":"Create Advance Invoice Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAdvanceInvoice"},"examples":{"Minimal":{"value":{"items":[{"name":"Satellite Communication Module","quantity":1,"price":1500}],"payments":[{"type":"bank_transfer"}]},"description":"Minimal advance invoice with payment (required for non-draft)"},"With customer":{"value":{"customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Thermal Shielding Panel","quantity":1,"price":850}],"payments":[{"type":"bank_transfer"}]},"description":"Document with inline customer (saved to database by default)"},"With tax":{"value":{"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"name":"EVA Toolkit - Standard","quantity":8,"price":150,"taxes":[{"rate":22}]},{"name":"Orbital Navigation License","quantity":10,"price":120,"taxes":[{"rate":22}]}],"payments":[{"type":"bank_transfer"}]},"description":"Document with tax calculations (2 items, both with 22% VAT)"},"Draft (no payment)":{"value":{"items":[{"name":"Satellite Communication Module","quantity":1,"price":1500}],"is_draft":true},"description":"Draft advance invoice - payments not required for drafts"},"With payment":{"value":{"items":[{"name":"Prepayment for Ground Station Installation","quantity":1,"price":5000}],"payments":[{"type":"bank_transfer"}]},"description":"Advance invoice with payment - marks advance as paid"},"Complete":{"value":{"date":"2025-03-15","note":"Thank you for your order. Equipment ships within 5 business days.","reference":"PO-2025-001","currency_code":"USD","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"items":[{"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"taxes":[{"rate":22}],"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"}},{"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"taxes":[{"rate":22}],"metadata":{"license_type":"enterprise","seats":"50"}}],"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"payments":[{"type":"bank_transfer"}]},"description":"Complete document with all optional fields populated"}}}}},"responses":{"201":{"description":"Created Advance Invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvanceInvoice"},"examples":{"Minimal":{"value":{"id":"adv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"adv_item_6595a27b5d35015c3ef0c3fd","advance_invoice_id":"adv_6595a27b5d35015c3ef0c3fd","expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":1500,"total_due":0,"paid_in_full":true,"furs":null,"fina":null},"description":"Minimal advance_invoice response"},"With customer":{"value":{"id":"adv_6595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00002","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Nebula Propulsion Labs"},"items":[{"id":"adv_item_6595a27b5d35015c3ef0c3fe","advance_invoice_id":"adv_6595a27b5d35015c3ef0c3fe","expense_id":null,"item_id":null,"name":"Thermal Shielding Panel","description":null,"translations":{},"quantity":1,"price":850,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":850,"total_with_tax":850,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":850,"total_with_tax":850,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":850,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":0,"total_due":750,"paid_in_full":false,"furs":null,"fina":null},"description":"advance_invoice with customer response"},"With tax":{"value":{"id":"adv_6595a27b5d35015c3ef0c3ff","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00003","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"id":"adv_item_6595a27b5d35015c3ef0c3ff","advance_invoice_id":"adv_6595a27b5d35015c3ef0c3ff","expense_id":null,"item_id":null,"name":"EVA Toolkit - Standard","description":null,"translations":{},"quantity":8,"price":150,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"},{"id":"adv_item_6595a27b5d35015c3ef0c400","advance_invoice_id":"adv_6595a27b5d35015c3ef0c3ff","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":null,"translations":{},"quantity":10,"price":120,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":2400,"total_with_tax":2928,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":2400,"rate":22,"amount":528,"reverse_charge":false,"tax_id":null}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":0,"total_due":2928,"paid_in_full":false,"furs":null,"fina":null},"description":"advance_invoice with tax calculations response"},"With payment":{"value":{"id":"adv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"adv_item_6595a27b5d35015c3ef0c3fd","advance_invoice_id":"adv_6595a27b5d35015c3ef0c3fd","expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":5000,"total_due":0,"paid_in_full":true,"furs":null,"fina":null,"payments":[{"id":"pmt_6595a27b5d35015c3ef0c3fd","invoice_id":null,"credit_note_id":null,"advance_invoice_id":"adv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","amount":5000,"type":"bank_transfer","date":"2026-01-01T00:00:00.000Z","reference":null,"note":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}]},"description":"Advance invoice created with payment - paid in full"},"Complete":{"value":{"id":"adv_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"adv_item_6595a27b5d35015c3ef0c402","advance_invoice_id":"adv_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"adv_item_6595a27b5d35015c3ef0c403","advance_invoice_id":"adv_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":0,"total_due":10370,"paid_in_full":false,"furs":null,"fina":null},"description":"Complete advance_invoice response with all fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getAdvanceInvoices","summary":"List all advance invoices","description":"Retrieve a paginated list of advance invoices with optional filtering and sorting. Supports cursor-based pagination, JSON querying with MongoDB-style operators, full-text search, and sorting.","security":[{"Bearer":[]}],"tags":["Advance Invoices"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","number","date","total","total_with_tax","created_at","updated_at","-id","-number","-date","-total","-total_with_tax","-created_at","-updated_at"]},{"type":"array","items":{"type":"string","enum":["id","number","date","total","total_with_tax","created_at","updated_at","-id","-number","-date","-total","-total_with_tax","-created_at","-updated_at"]}}],"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at, paid_in_full, voided_at, total_paid\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at, paid_in_full, voided_at, total_paid\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"type":"string","description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","example":"Acme Corporation"},"required":false,"description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","name":"search","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `payments` - Payment records linked to this advance invoice\n- `document_relations` - Linked documents (invoices, credit notes, etc.)\n\n**Usage:**\n`?include=payments`\n`?include=payments,document_relations`","example":"payments"},"required":false,"description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `payments` - Payment records linked to this advance invoice\n- `document_relations` - Linked documents (invoices, credit notes, etc.)\n\n**Usage:**\n`?include=payments`\n`?include=payments,document_relations`","name":"include","in":"query"},{"schema":{"type":"boolean","description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items."},"required":false,"description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.","name":"deleted","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of Advance Invoices","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvanceInvoiceList"},"examples":{"200":{"value":{"data":[{"id":"adv_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"adv_item_6595a27b5d35015c3ef0c402","advance_invoice_id":"adv_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"adv_item_6595a27b5d35015c3ef0c403","advance_invoice_id":"adv_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":0,"total_due":10370,"paid_in_full":false,"furs":null,"fina":null}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of advance invoices"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/advance-invoices/custom":{"post":{"operationId":"createCustomAdvanceInvoice","summary":"Create advance invoice with pre-calculated totals","description":"Advanced endpoint for importing advance invoices that already have authoritative pre-calculated totals. Do not use this for normal advance invoice creation. Prefer the standard create endpoint unless your integration must preserve exact external totals from an ERP, OCR, migration, or accounting system.\nThe caller provides `total`, `total_with_tax`, `total_discount`, and `taxes` at the document level, and `total`/`total_with_tax` on each line item.\nWhen `calculation_mode` is omitted, Space Invoices preserves pass-through behavior and accepts the supplied totals as-is.\nWhen `calculation_mode` is provided, Space Invoices validates the supplied totals against that calculation mode before creating the document.\nAll other logic (numbering, fiscalization, customer handling, payments, lifecycle hooks) is identical to the standard create endpoint.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Advance Invoices"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"description":"Custom Advance Invoice Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomCreateAdvanceInvoice"},"examples":{"Custom with totals":{"value":{"total":5000,"total_with_tax":6100,"taxes":[{"rate":22,"base":5000,"amount":1100}],"items":[{"name":"Prepayment for Services","quantity":1,"price":5000,"total":5000,"total_with_tax":6100,"taxes":[{"rate":22}]}],"payments":[{"type":"bank_transfer"}]},"description":"Custom advance invoice with pre-calculated totals from external system"}}}}},"responses":{"201":{"description":"Created Advance Invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvanceInvoice"},"examples":{"Minimal":{"value":{"id":"adv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"adv_item_6595a27b5d35015c3ef0c3fd","advance_invoice_id":"adv_6595a27b5d35015c3ef0c3fd","expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":1500,"total_due":0,"paid_in_full":true,"furs":null,"fina":null},"description":"Minimal advance_invoice response"},"With customer":{"value":{"id":"adv_6595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00002","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Nebula Propulsion Labs"},"items":[{"id":"adv_item_6595a27b5d35015c3ef0c3fe","advance_invoice_id":"adv_6595a27b5d35015c3ef0c3fe","expense_id":null,"item_id":null,"name":"Thermal Shielding Panel","description":null,"translations":{},"quantity":1,"price":850,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":850,"total_with_tax":850,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":850,"total_with_tax":850,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":850,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":0,"total_due":750,"paid_in_full":false,"furs":null,"fina":null},"description":"advance_invoice with customer response"},"With tax":{"value":{"id":"adv_6595a27b5d35015c3ef0c3ff","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00003","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"id":"adv_item_6595a27b5d35015c3ef0c3ff","advance_invoice_id":"adv_6595a27b5d35015c3ef0c3ff","expense_id":null,"item_id":null,"name":"EVA Toolkit - Standard","description":null,"translations":{},"quantity":8,"price":150,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"},{"id":"adv_item_6595a27b5d35015c3ef0c400","advance_invoice_id":"adv_6595a27b5d35015c3ef0c3ff","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":null,"translations":{},"quantity":10,"price":120,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":2400,"total_with_tax":2928,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":2400,"rate":22,"amount":528,"reverse_charge":false,"tax_id":null}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":0,"total_due":2928,"paid_in_full":false,"furs":null,"fina":null},"description":"advance_invoice with tax calculations response"},"With payment":{"value":{"id":"adv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"adv_item_6595a27b5d35015c3ef0c3fd","advance_invoice_id":"adv_6595a27b5d35015c3ef0c3fd","expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":5000,"total_due":0,"paid_in_full":true,"furs":null,"fina":null,"payments":[{"id":"pmt_6595a27b5d35015c3ef0c3fd","invoice_id":null,"credit_note_id":null,"advance_invoice_id":"adv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","amount":5000,"type":"bank_transfer","date":"2026-01-01T00:00:00.000Z","reference":null,"note":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}]},"description":"Advance invoice created with payment - paid in full"},"Complete":{"value":{"id":"adv_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"adv_item_6595a27b5d35015c3ef0c402","advance_invoice_id":"adv_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"adv_item_6595a27b5d35015c3ef0c403","advance_invoice_id":"adv_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":0,"total_due":10370,"paid_in_full":false,"furs":null,"fina":null},"description":"Complete advance_invoice response with all fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/advance-invoices/{id}":{"get":{"operationId":"getAdvanceInvoiceById","summary":"Get advance invoice by ID","description":"Retrieve a single advance invoice by its unique identifier. Returns the complete advance invoice details including all line items, customer information, and calculated totals.","security":[{"Bearer":[]}],"tags":["Advance Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `payments` - Payment records linked to this advance invoice\n- `document_relations` - Linked documents (invoices, credit notes, etc.)\n\n**Usage:**\n`?include=payments`\n`?include=payments,document_relations`","example":"payments"},"required":false,"description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `payments` - Payment records linked to this advance invoice\n- `document_relations` - Linked documents (invoices, credit notes, etc.)\n\n**Usage:**\n`?include=payments`\n`?include=payments,document_relations`","name":"include","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Advance Invoice instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvanceInvoice"},"examples":{"200":{"value":{"id":"adv_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"adv_item_6595a27b5d35015c3ef0c402","advance_invoice_id":"adv_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"adv_item_6595a27b5d35015c3ef0c403","advance_invoice_id":"adv_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":0,"total_due":10370,"paid_in_full":false,"furs":null,"fina":null},"description":"Complete advance_invoice response with all fields"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateAdvanceInvoice","summary":"Update an advance invoice","description":"Update an existing advance invoice.\nCreates a version snapshot before applying changes.\nCannot update voided or FURS-fiscalized advance invoices.\nIf items are provided, they replace all existing items.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Advance Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Advance Invoice Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAdvanceInvoice"},"examples":{"Update note":{"value":{"note":"Prepayment received. Thank you!","change_reason":"Added confirmation note"},"description":"Update only the note field"},"Update items":{"value":{"items":[{"name":"Prepayment for Ground Station Phase 1","quantity":1,"price":5000},{"name":"Prepayment for Antenna Components","quantity":1,"price":2000}],"change_reason":"Corrected prepayment breakdown"},"description":"Replace all items (recalculates totals)"}}}}},"responses":{"200":{"description":"Updated Advance Invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvanceInvoice"},"examples":{"200":{"value":{"id":"adv_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"adv_item_6595a27b5d35015c3ef0c402","advance_invoice_id":"adv_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"adv_item_6595a27b5d35015c3ef0c403","advance_invoice_id":"adv_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":0,"total_due":10370,"paid_in_full":false,"furs":null,"fina":null},"description":"Complete advance_invoice response with all fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/advance-invoices/{id}/versions":{"get":{"operationId":"getAdvanceInvoiceVersions","summary":"Get advance invoice version history","description":"Retrieve the version history for an advance invoice. Each version represents the document state before an update was applied.","security":[{"Bearer":[]}],"tags":["Advance Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Advance invoice version history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentVersionList"},"examples":{"200":{"value":{"versions":[{"id":"ver_abc123","document_type":"advance_invoice","document_id":"adv_6595a27b5d35015c3ef0c3fd","version":2,"snapshot":{"id":"adv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"adv_item_6595a27b5d35015c3ef0c3fd","advance_invoice_id":"adv_6595a27b5d35015c3ef0c3fd","expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":1500,"total_due":0,"paid_in_full":true,"furs":null,"fina":null},"changed_fields":["note"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Added confirmation note","created_at":"2025-01-15T10:30:00.000Z"},{"id":"ver_xyz789","document_type":"advance_invoice","document_id":"adv_6595a27b5d35015c3ef0c3fd","version":1,"snapshot":{"id":"adv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"adv_item_6595a27b5d35015c3ef0c3fd","advance_invoice_id":"adv_6595a27b5d35015c3ef0c3fd","expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":1500,"total_due":0,"paid_in_full":true,"furs":null,"fina":null},"changed_fields":["items"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Corrected prepayment breakdown","created_at":"2025-01-14T15:00:00.000Z"}],"count":2},"description":"Version history with 2 updates"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/advance-invoices/{id}/versions/{version}":{"get":{"operationId":"getAdvanceInvoiceVersion","summary":"Get specific advance invoice version","description":"Retrieve a specific version snapshot of an advance invoice.","security":[{"Bearer":[]}],"tags":["Advance Invoices"],"parameters":[{"schema":{"type":"string","description":"Advance Invoice ID"},"required":true,"description":"Advance Invoice ID","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"description":"Version number"},"required":true,"description":"Version number","name":"version","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Advance invoice version snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentVersion"},"examples":{"200":{"value":{"id":"ver_abc123","document_type":"advance_invoice","document_id":"adv_6595a27b5d35015c3ef0c3fd","version":1,"snapshot":{"id":"adv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"adv_item_6595a27b5d35015c3ef0c3fd","advance_invoice_id":"adv_6595a27b5d35015c3ef0c3fd","expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","total_paid":1500,"total_due":0,"paid_in_full":true,"furs":null,"fina":null},"changed_fields":["items"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Corrected prepayment breakdown","created_at":"2025-01-14T15:00:00.000Z"},"description":"Single version snapshot"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/advance-invoices/render":{"post":{"operationId":"renderAdvanceInvoicePreview","summary":"Render advance invoice preview","description":"Render an HTML preview of an advance invoice without saving to the database. Perfect for displaying live previews in advance invoice creation/edit forms. Supports both partial mode (allows incomplete data for drafts) and complete mode (validates all required fields).","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Advance Invoices"],"parameters":[{"schema":{"type":"string","enum":["modern","classic","condensed","minimal","fashion"],"description":"Document template design to use. When not specified, uses the entity's configured template.","example":"modern"},"required":false,"description":"Document template design to use. When not specified, uses the entity's configured template.","name":"template","in":"query"},{"schema":{"type":["string","null"],"minLength":2,"maxLength":5,"description":"Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.","example":"sl-SI"},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.","name":"locale","in":"query"},{"schema":{"type":["string","null"],"minLength":2,"maxLength":5,"description":"Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.","example":"en-US"},"required":false,"description":"Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.","name":"language","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"true","description":"Whether to treat the document as partial (allows incomplete data) or complete (validates all required fields)","example":"true"},"required":false,"description":"Whether to treat the document as partial (allows incomplete data) or complete (validates all required fields)","name":"partial","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override UPN QR enabled setting for preview"},"required":false,"description":"Override UPN QR enabled setting for preview","name":"upn_qr_enabled","in":"query"},{"schema":{"type":"string","enum":["qr_only","full_slip"],"description":"Override UPN QR display mode for preview"},"required":false,"description":"Override UPN QR display mode for preview","name":"upn_qr_display_mode","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override EPC QR enabled setting for preview"},"required":false,"description":"Override EPC QR enabled setting for preview","name":"epc_qr_enabled","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override Croatian HUB3 PDF417 barcode enabled setting for preview"},"required":false,"description":"Override Croatian HUB3 PDF417 barcode enabled setting for preview","name":"hub3_qr_enabled","in":"query"},{"schema":{"type":"string","minLength":4,"maxLength":4,"pattern":"^[A-Z]{4}$","description":"Override HUB3 purpose code for preview"},"required":false,"description":"Override HUB3 purpose code for preview","name":"hub3_qr_purpose_code","in":"query"},{"schema":{"type":"string","pattern":"^HR\\d{2}$","description":"Override HUB3 Croatian reference model for preview"},"required":false,"description":"Override HUB3 Croatian reference model for preview","name":"hub3_qr_reference_model","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Advance Invoice Data","required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PartialAdvanceInvoicePreview"},{"$ref":"#/components/schemas/CompleteAdvanceInvoicePreview"}]},"examples":{"Partial":{"value":{"items":[{"name":"Prepayment - Project Setup","quantity":1,"price":2500}],"customer":{"name":"Acme Corp"}},"description":"Partial advance invoice render with minimal data"},"Complete":{"value":{"items":[{"name":"Prepayment - Project Setup","quantity":1,"price":2500,"taxes":[{"rate":22}]}],"customer":{"name":"Acme Corp","address":"123 Main St","city":"New York","post_code":"10001","country":"US"},"date":"2025-01-15"},"description":"Complete advance invoice render with full data"}}}}},"responses":{"200":{"description":"Rendered document (HTML)","content":{"text/html":{"schema":{"type":"string","description":"Fully formatted HTML document ready for display"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/advance-invoices/{id}/void":{"post":{"operationId":"voidAdvanceInvoice","summary":"Void an advance invoice","description":"Void an advance invoice for technical reasons (duplicate, error, etc.). For FURS-fiscalized advance invoices, automatically submits technical cancellation to FURS. All linked payments are soft-deleted, reversing their effect on invoice totals.","tags":["Advance Invoices"],"x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Void Advance Invoice Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"description":"Technical reason for voiding (e.g., 'Duplicate advance invoice', 'Technical error')","example":"Duplicate advance invoice - issued in error"},"has_original_document":{"type":["boolean","null"],"description":"Whether the original physical/manual PT document is still available.","example":true}}},"examples":{"Void Advance Invoice":{"value":{"reason":"Duplicate advance invoice created by mistake"}}}}}},"responses":{"200":{"description":"Voided Advance Invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvanceInvoice"},"examples":{"Voided Advance Invoice":{"value":{"id":"ai_abc123","voided_at":"2026-01-20T12:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/delivery-notes/shareable/{shareableId}":{"get":{"operationId":"getShareableDeliveryNote","summary":"View shareable delivery note","description":"Retrieve delivery note data using a shareable token. No authentication required. Returns full delivery note data for rendering.","security":[],"tags":["Delivery Notes"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"}],"responses":{"200":{"description":"Delivery Note data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryNote"},"examples":{"200":{"value":{"id":"dn_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"dn_item_6595a27b5d35015c3ef0c402","delivery_note_id":"dn_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"dn_item_6595a27b5d35015c3ef0c403","delivery_note_id":"dn_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"description":"Complete delivery_note response with all fields"}}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/delivery-notes/shareable/{shareableId}/html":{"get":{"operationId":"getShareableDeliveryNoteHtml","summary":"Get shareable delivery note as HTML","description":"Get delivery note as HTML preview using a shareable token. No authentication required. Supports multiple languages via locale query parameter.","security":[],"tags":["Delivery Notes"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale."},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale.","name":"locale","in":"query"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Language for document labels/translations. Defaults to locale value."},"required":false,"description":"Language for document labels/translations. Defaults to locale value.","name":"language","in":"query"}],"responses":{"200":{"description":"Rendered document (HTML)","content":{"text/html":{"schema":{"type":"string","description":"Fully formatted HTML document ready for display"}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/delivery-notes/shareable/{shareableId}/pdf":{"get":{"operationId":"getShareableDeliveryNotePdf","summary":"Download shareable delivery note as PDF","description":"Download delivery note as PDF using a shareable token. No authentication required. Supports multiple languages via locale query parameter.","security":[],"tags":["Delivery Notes"],"parameters":[{"schema":{"type":"string","description":"Shareable document token"},"required":true,"description":"Shareable document token","name":"shareableId","in":"path"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale."},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). Defaults to entity locale.","name":"locale","in":"query"},{"schema":{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"],"description":"Language for document labels/translations. Defaults to locale value."},"required":false,"description":"Language for document labels/translations. Defaults to locale value.","name":"language","in":"query"}],"responses":{"200":{"description":"PDF document","content":{"application/pdf":{"schema":{"type":"string","format":"binary","description":"PDF document binary"}}}},"404":{"description":"Invalid or expired shareable link"}}}},"/delivery-notes":{"post":{"operationId":"createDeliveryNote","summary":"Create a new delivery note","description":"Create a new delivery note with line items.\nThis is the recommended endpoint for normal delivery note creation. Use it when Space Invoices should calculate line totals, taxes, discounts, document totals, numbering, customer handling, and lifecycle hooks from the supplied business inputs.\nCustomer is optional - can be omitted or added inline without referencing a customer_id.\nThe delivery note number is auto-generated based on the entity's number format settings.\nTaxes are calculated automatically based on the tax rates provided.\nSet hide_prices=true to create a packing list without prices.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Delivery Notes"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"description":"Create Delivery Note Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeliveryNote"},"examples":{"Minimal":{"value":{"items":[{"name":"Satellite Communication Module","quantity":1,"price":1500}]},"description":"Minimal document with single item, no customer, no taxes"},"With customer":{"value":{"customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Thermal Shielding Panel","quantity":1,"price":850}]},"description":"Document with inline customer (saved to database by default)"},"With referenced customer":{"value":{"customer_id":"cus_6595a27b5d35015c3ef0c3fd","items":[{"name":"Orbital Navigation License","quantity":1,"price":5000}]},"description":"Document referencing existing customer by ID"},"With tax":{"value":{"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"name":"EVA Toolkit - Standard","quantity":8,"price":150,"taxes":[{"rate":22}]},{"name":"Orbital Navigation License","quantity":10,"price":120,"taxes":[{"rate":22}]}]},"description":"Document with tax calculations (2 items, both with 22% VAT)"},"With tax classification":{"value":{"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"name":"Mission Control Console","quantity":8,"price":150,"taxes":[{"classification":"standard"}]},{"name":"Launch Safety Manual","quantity":5,"price":20,"taxes":[{"classification":"reduced"}]}]},"description":"Document using tax classification. Rate is resolved from entity's taxes by classification (e.g., \"standard\", \"reduced\", \"zero\"). Classification must exist on entity."},"With gross price":{"value":{"customer":{"name":"Orbital Systems GmbH"},"items":[{"name":"Ground Station Antenna Array","quantity":1,"gross_price":15250,"taxes":[{"rate":22}]}]},"description":"Document with gross pricing. Net price back-calculated: 15250 / 1.22 = 12500. Use gross prices for stable totals when VIES reverse charge may apply."},"With service period":{"value":{"date":"2025-03-01","date_service":"2025-03-01","date_service_to":"2025-03-31","customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Telemetry platform hosting","quantity":1,"price":1200}]},"description":"Document with a service period. Use date_service/date_service_to for subscriptions, retainers, and revenue recognition periods."},"With line discounts":{"value":{"calculation_mode":"b2b_standard","customer":{"name":"Horizon Launch Systems Inc."},"items":[{"name":"Mission planning package","quantity":1,"price":2000,"discounts":[{"type":"percent","value":10}],"taxes":[{"rate":22}]},{"name":"Launch readiness review","quantity":1,"price":500,"discounts":[{"type":"amount","value":50}],"taxes":[{"rate":22}]}]},"description":"Document with percentage and fixed line discounts. Discounts are applied per line before tax in b2b_standard mode."},"With financial categories":{"value":{"customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Ground Segment Implementation","quantity":1,"price":2500,"financial_category_id":"fcat_services"},{"name":"Telemetry platform hosting","quantity":1,"price":300,"financial_category_id":"fcat_hosting"}]},"description":"Document with per-line financial categories for revenue-by-category reporting. Use category_assignments when assigning by request item index instead."},"With category assignments":{"value":{"customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Ground Segment Implementation","quantity":1,"price":2500},{"name":"Telemetry platform hosting","quantity":1,"price":300}],"category_assignments":[{"item_index":0,"financial_category_id":"fcat_services"},{"item_index":1,"financial_category_id":"fcat_hosting"}]},"description":"Document with category assignments by line index. This is useful when item payloads come from an external system and categories are mapped separately."},"With rounding correction":{"value":{"customer":{"name":"Legacy Payload Systems Ltd."},"expected_total_with_tax":122.01,"items":[{"name":"Imported service line","quantity":1,"price":100,"taxes":[{"rate":22}]}]},"description":"Document with expected_total_with_tax for small external rounding differences. The API calculates a rounding correction within the allowed tolerance."},"With item prefill":{"value":{"customer":{"name":"Nebula Propulsion Labs"},"items":[{"item_id":"item_6595a27b5d35015c3ef0c3fd","quantity":5}]},"description":"Document with item prefilled from catalog. Name, price, and taxes are loaded from the catalog item. Only quantity needs to be specified."},"With item prefill and overrides":{"value":{"customer":{"name":"Alex Carter"},"items":[{"item_id":"item_6595a27b5d35015c3ef0c3fd","quantity":10,"price":1400,"description":"Bulk order discount applied"},{"item_id":"item_6595a27b5d35015c3ef0c3fe","quantity":2}]},"description":"Document with multiple catalog items. First item overrides price and description from catalog. Request values always take precedence over catalog values."},"With translations":{"value":{"items":[{"name":"Satellite Communication Module","quantity":1,"price":1500,"translations":{"name":{"de-DE":"Satelliten-Kommunikationsmodul"},"description":{"de-DE":"Hochleistungs-Kommunikationsmodul fuer den Orbitaleinsatz"}}}],"note":"Thank you for your business.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."}}},"description":"Minimal document with translated document and line-item content"},"Hide prices":{"value":{"hide_prices":true,"customer":{"name":"Nebula Propulsion Labs"},"items":[{"name":"Replacement parts shipment","quantity":1,"price":850}]},"description":"Create a delivery note that renders as a packing list by hiding item prices and totals."},"Complete":{"value":{"date":"2025-03-15","note":"Thank you for your order. Equipment ships within 5 business days.","reference":"PO-2025-001","currency_code":"USD","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"items":[{"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"taxes":[{"rate":22}],"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"}},{"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"taxes":[{"rate":22}],"metadata":{"license_type":"enterprise","seats":"50"}}],"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"hide_prices":false},"description":"Complete document with all optional fields populated"}}}}},"responses":{"201":{"description":"Created Delivery Note","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryNote"},"examples":{"Minimal":{"value":{"id":"dn_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"dn_item_6595a27b5d35015c3ef0c3fd","delivery_note_id":"dn_6595a27b5d35015c3ef0c3fd","expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"description":"Minimal delivery_note response"},"With customer":{"value":{"id":"dn_6595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00002","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Nebula Propulsion Labs"},"items":[{"id":"dn_item_6595a27b5d35015c3ef0c3fe","delivery_note_id":"dn_6595a27b5d35015c3ef0c3fe","expense_id":null,"item_id":null,"name":"Thermal Shielding Panel","description":null,"translations":{},"quantity":1,"price":850,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":850,"total_with_tax":850,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":850,"total_with_tax":850,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":850,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"description":"delivery_note with customer response"},"With referenced customer":{"value":{"id":"dn_6595a27b5d35015c3ef0c401","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00004","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":"cus_6595a27b5d35015c3ef0c3fd","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","country":"US"},"items":[{"id":"dn_item_6595a27b5d35015c3ef0c401","delivery_note_id":"dn_6595a27b5d35015c3ef0c401","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":null,"translations":{},"quantity":1,"price":5000,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":5000,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":5000,"total_with_tax":5000,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":5000,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"description":"delivery_note with referenced customer response"},"With tax":{"value":{"id":"dn_6595a27b5d35015c3ef0c3ff","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00003","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"id":"dn_item_6595a27b5d35015c3ef0c3ff","delivery_note_id":"dn_6595a27b5d35015c3ef0c3ff","expense_id":null,"item_id":null,"name":"EVA Toolkit - Standard","description":null,"translations":{},"quantity":8,"price":150,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"},{"id":"dn_item_6595a27b5d35015c3ef0c400","delivery_note_id":"dn_6595a27b5d35015c3ef0c3ff","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":null,"translations":{},"quantity":10,"price":120,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":2400,"total_with_tax":2928,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":2400,"rate":22,"amount":528,"reverse_charge":false,"tax_id":null}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"description":"delivery_note with tax calculations response"},"Complete":{"value":{"id":"dn_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"dn_item_6595a27b5d35015c3ef0c402","delivery_note_id":"dn_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"dn_item_6595a27b5d35015c3ef0c403","delivery_note_id":"dn_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"description":"Complete delivery_note response with all fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getDeliveryNotes","summary":"List all delivery notes","description":"Retrieve a paginated list of delivery notes with optional filtering and sorting.\nSupports cursor-based pagination, flexible JSON querying with MongoDB-style operators, full-text search, and sorting.","security":[{"Bearer":[]}],"tags":["Delivery Notes"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","number","date","total","total_with_tax","created_at","updated_at","-id","-number","-date","-total","-total_with_tax","-created_at","-updated_at"]},{"type":"array","items":{"type":"string","enum":["id","number","date","total","total_with_tax","created_at","updated_at","-id","-number","-date","-total","-total_with_tax","-created_at","-updated_at"]}}],"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"type":"string","description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","example":"Acme Corporation"},"required":false,"description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","name":"search","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `document_relations` - Linked documents (invoices, etc.)\n\n**Usage:**\n`?include=document_relations`","example":"document_relations"},"required":false,"description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `document_relations` - Linked documents (invoices, etc.)\n\n**Usage:**\n`?include=document_relations`","name":"include","in":"query"},{"schema":{"type":"boolean","description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items."},"required":false,"description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.","name":"deleted","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of Delivery Notes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryNoteList"},"examples":{"200":{"value":{"data":[{"id":"dn_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"dn_item_6595a27b5d35015c3ef0c402","delivery_note_id":"dn_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"dn_item_6595a27b5d35015c3ef0c403","delivery_note_id":"dn_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of delivery notes"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/delivery-notes/custom":{"post":{"operationId":"createCustomDeliveryNote","summary":"Create delivery note with pre-calculated totals","description":"Advanced endpoint for importing delivery notes that already have authoritative pre-calculated totals. Do not use this for normal delivery note creation. Prefer the standard create endpoint unless your integration must preserve exact external totals from an ERP, OCR, migration, or accounting system.\nThe caller provides `total`, `total_with_tax`, `total_discount`, and `taxes` at the document level, and `total`/`total_with_tax` on each line item.\nWhen `calculation_mode` is omitted, Space Invoices preserves pass-through behavior and accepts the supplied totals as-is.\nWhen `calculation_mode` is provided, Space Invoices validates the supplied totals against that calculation mode before creating the document.\nAll other logic (numbering, customer handling, lifecycle hooks) is identical to the standard create endpoint.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Delivery Notes"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"description":"Custom Delivery Note Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomCreateDeliveryNote"},"examples":{"Custom with totals":{"value":{"total":5000,"total_with_tax":6100,"taxes":[{"rate":22,"base":5000,"amount":1100}],"items":[{"name":"Website Redesign","quantity":1,"price":5000,"total":5000,"total_with_tax":6100,"taxes":[{"rate":22}]}]},"description":"Custom delivery note with pre-calculated totals from external system"}}}}},"responses":{"201":{"description":"Created Delivery Note","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryNote"},"examples":{"Minimal":{"value":{"id":"dn_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"dn_item_6595a27b5d35015c3ef0c3fd","delivery_note_id":"dn_6595a27b5d35015c3ef0c3fd","expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"description":"Minimal delivery_note response"},"With customer":{"value":{"id":"dn_6595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00002","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Nebula Propulsion Labs"},"items":[{"id":"dn_item_6595a27b5d35015c3ef0c3fe","delivery_note_id":"dn_6595a27b5d35015c3ef0c3fe","expense_id":null,"item_id":null,"name":"Thermal Shielding Panel","description":null,"translations":{},"quantity":1,"price":850,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":850,"total_with_tax":850,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":850,"total_with_tax":850,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":850,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"description":"delivery_note with customer response"},"With referenced customer":{"value":{"id":"dn_6595a27b5d35015c3ef0c401","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00004","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":"cus_6595a27b5d35015c3ef0c3fd","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","country":"US"},"items":[{"id":"dn_item_6595a27b5d35015c3ef0c401","delivery_note_id":"dn_6595a27b5d35015c3ef0c401","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":null,"translations":{},"quantity":1,"price":5000,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":5000,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":5000,"total_with_tax":5000,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":5000,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"description":"delivery_note with referenced customer response"},"With tax":{"value":{"id":"dn_6595a27b5d35015c3ef0c3ff","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00003","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":{"name":"Horizon Launch Systems Inc."},"items":[{"id":"dn_item_6595a27b5d35015c3ef0c3ff","delivery_note_id":"dn_6595a27b5d35015c3ef0c3ff","expense_id":null,"item_id":null,"name":"EVA Toolkit - Standard","description":null,"translations":{},"quantity":8,"price":150,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"},{"id":"dn_item_6595a27b5d35015c3ef0c400","delivery_note_id":"dn_6595a27b5d35015c3ef0c3ff","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":null,"translations":{},"quantity":10,"price":120,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c3fd"}],"discounts":[],"type":null,"unit":null,"total":1200,"total_with_tax":1464,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":2400,"total_with_tax":2928,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":2400,"rate":22,"amount":528,"reverse_charge":false,"tax_id":null}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"description":"delivery_note with tax calculations response"},"Complete":{"value":{"id":"dn_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"dn_item_6595a27b5d35015c3ef0c402","delivery_note_id":"dn_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"dn_item_6595a27b5d35015c3ef0c403","delivery_note_id":"dn_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"description":"Complete delivery_note response with all fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/delivery-notes/{id}":{"get":{"operationId":"getDeliveryNoteById","summary":"Get delivery note by ID","description":"Retrieve a single delivery note by its unique identifier. Returns the complete delivery note details including all line items, customer information, and calculated totals.","security":[{"Bearer":[]}],"tags":["Delivery Notes"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `document_relations` - Linked documents (invoices, etc.)\n\n**Usage:**\n`?include=document_relations`","example":"document_relations"},"required":false,"description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `document_relations` - Linked documents (invoices, etc.)\n\n**Usage:**\n`?include=document_relations`","name":"include","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Delivery Note instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryNote"},"examples":{"200":{"value":{"id":"dn_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"dn_item_6595a27b5d35015c3ef0c402","delivery_note_id":"dn_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"dn_item_6595a27b5d35015c3ef0c403","delivery_note_id":"dn_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"description":"Complete delivery_note response with all fields"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateDeliveryNote","summary":"Update a delivery note","description":"Update an existing delivery note.\nCreates a version snapshot before applying changes.\nCannot update voided delivery notes.\nIf items are provided, they replace all existing items.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Delivery Notes"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Delivery Note Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDeliveryNote"},"examples":{"Update note":{"value":{"note":"Updated delivery instructions","change_reason":"Added delivery note"},"description":"Update only the note field"},"Update items":{"value":{"items":[{"name":"Mission Planning Services","quantity":40,"price":125},{"name":"Design Services","quantity":10,"price":100}],"change_reason":"Revised item list"},"description":"Replace all items (recalculates totals)"},"Toggle hide prices":{"value":{"hide_prices":true,"change_reason":"Switch to packing list mode"},"description":"Toggle price visibility on the delivery note"}}}}},"responses":{"200":{"description":"Updated Delivery Note","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryNote"},"examples":{"200":{"value":{"id":"dn_6595a27b5d35015c3ef0c402","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"DOC-2025-001","date":"2025-03-15T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"USA","country_code":"US","tax_number":"59-8765432"},"customer_id":"cus_6595a27b5d35015c3ef0c403","customer":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"USA","country_code":"US","tax_number":"74-1234567"},"items":[{"id":"dn_item_6595a27b5d35015c3ef0c402","delivery_note_id":"dn_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","translations":{"name":{"de-DE":"Bodenstations-Antennenanlage"},"description":{"de-DE":"Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"}},"quantity":2,"price":12500,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":25000,"total_with_tax":30500,"total_converted":null,"total_with_tax_converted":null,"metadata":{"project_code":"MSN-2025-001","department":"Ground Operations"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"},{"id":"dn_item_6595a27b5d35015c3ef0c403","delivery_note_id":"dn_6595a27b5d35015c3ef0c402","expense_id":null,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"quantity":1,"price":5000,"gross_price":null,"taxes":[{"rate":22,"tax_id":"tax_6595a27b5d35015c3ef0c402"}],"discounts":[],"type":null,"unit":null,"total":5000,"total_with_tax":6100,"total_converted":null,"total_with_tax_converted":null,"metadata":{"license_type":"enterprise","seats":"50"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z"}],"note":"Thank you for your order. Equipment ships within 5 business days.","translations":{"note":{"de-DE":"Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."},"payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"footer":{"de-DE":"Fragen? Kontaktieren Sie billing@starward.example."},"signature":{"de-DE":"Starward Equipment Team"}},"reference":"PO-2025-001","total":30000,"total_with_tax":36600,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"base":30000,"rate":22,"amount":6600,"reverse_charge":false,"tax_id":null}],"date_year":2025,"metadata":{"project_id":"MSN-2025-001","contract_id":"ORB-2024-789"},"created_at":"2025-03-15T00:00:00.000Z","updated_at":"2025-03-15T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"description":"Complete delivery_note response with all fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/delivery-notes/{id}/versions":{"get":{"operationId":"getDeliveryNoteVersions","summary":"Get delivery note version history","description":"Retrieve the version history for a delivery note. Each version represents the document state before an update was applied.","security":[{"Bearer":[]}],"tags":["Delivery Notes"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Delivery Note version history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentVersionList"},"examples":{"200":{"value":{"versions":[{"id":"ver_abc123","document_type":"delivery_note","document_id":"del_6595a27b5d35015c3ef0c3fd","version":2,"snapshot":{"id":"dn_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"dn_item_6595a27b5d35015c3ef0c3fd","delivery_note_id":"dn_6595a27b5d35015c3ef0c3fd","expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"changed_fields":["note"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Updated delivery instructions","created_at":"2025-01-15T10:30:00.000Z"},{"id":"ver_xyz789","document_type":"delivery_note","document_id":"del_6595a27b5d35015c3ef0c3fd","version":1,"snapshot":{"id":"dn_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"dn_item_6595a27b5d35015c3ef0c3fd","delivery_note_id":"dn_6595a27b5d35015c3ef0c3fd","expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"changed_fields":["items"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Revised item list","created_at":"2025-01-14T15:00:00.000Z"}],"count":2},"description":"Version history with 2 updates"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/delivery-notes/{id}/versions/{version}":{"get":{"operationId":"getDeliveryNoteVersion","summary":"Get specific delivery note version","description":"Retrieve a specific version snapshot of a delivery note.","security":[{"Bearer":[]}],"tags":["Delivery Notes"],"parameters":[{"schema":{"type":"string","description":"Delivery Note ID"},"required":true,"description":"Delivery Note ID","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"description":"Version number"},"required":true,"description":"Version number","name":"version","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Delivery Note version snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentVersion"},"examples":{"200":{"value":{"id":"ver_abc123","document_type":"delivery_note","document_id":"del_6595a27b5d35015c3ef0c3fd","version":1,"snapshot":{"id":"dn_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","number":"2026-00001","date":"2026-01-01T00:00:00.000Z","currency_code":"USD","issuer":{"name":"Starward Equipment Co.","country":"United States","country_code":"US"},"customer_id":null,"customer":null,"items":[{"id":"dn_item_6595a27b5d35015c3ef0c3fd","delivery_note_id":"dn_6595a27b5d35015c3ef0c3fd","expense_id":null,"item_id":null,"name":"Satellite Communication Module","description":null,"translations":{},"quantity":1,"price":1500,"gross_price":null,"taxes":[],"discounts":[],"type":null,"unit":null,"total":1500,"total_with_tax":1500,"total_converted":null,"total_with_tax_converted":null,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z"}],"note":null,"translations":{},"reference":null,"total":1500,"total_with_tax":1500,"total_discount":0,"total_converted":null,"total_with_tax_converted":null,"shareable_id":null,"taxes":[{"rate":null,"tax_id":null,"base":1500,"amount":0,"reverse_charge":false}],"date_year":2026,"metadata":{},"created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","voided_at":null,"deleted_at":null,"exchange_rate":null,"rounding_correction":null,"transaction_type":"domestic","vies":null,"tax_clause":null,"signature":"{entity_name}","payment_terms":null,"hide_prices":false},"changed_fields":["items"],"user":{"id":"usr_123","name":"Alex Carter","email":"alex.carter@starward.example"},"reason":"Revised item list","created_at":"2025-01-14T15:00:00.000Z"},"description":"Single version snapshot"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/delivery-notes/render":{"post":{"operationId":"renderDeliveryNotePreview","summary":"Render delivery note preview","description":"Render an HTML preview of a delivery note without saving to the database. Perfect for displaying live previews in delivery note creation/edit forms. Supports both partial mode (allows incomplete data for drafts) and complete mode (validates all required fields).","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Delivery Notes"],"parameters":[{"schema":{"type":"string","enum":["modern","classic","condensed","minimal","fashion"],"description":"Document template design to use. When not specified, uses the entity's configured template.","example":"modern"},"required":false,"description":"Document template design to use. When not specified, uses the entity's configured template.","name":"template","in":"query"},{"schema":{"type":["string","null"],"minLength":2,"maxLength":5,"description":"Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.","example":"sl-SI"},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.","name":"locale","in":"query"},{"schema":{"type":["string","null"],"minLength":2,"maxLength":5,"description":"Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.","example":"en-US"},"required":false,"description":"Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.","name":"language","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"true","description":"Whether to treat the document as partial (allows incomplete data) or complete (validates all required fields)","example":"true"},"required":false,"description":"Whether to treat the document as partial (allows incomplete data) or complete (validates all required fields)","name":"partial","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override UPN QR enabled setting for preview"},"required":false,"description":"Override UPN QR enabled setting for preview","name":"upn_qr_enabled","in":"query"},{"schema":{"type":"string","enum":["qr_only","full_slip"],"description":"Override UPN QR display mode for preview"},"required":false,"description":"Override UPN QR display mode for preview","name":"upn_qr_display_mode","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override EPC QR enabled setting for preview"},"required":false,"description":"Override EPC QR enabled setting for preview","name":"epc_qr_enabled","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Override Croatian HUB3 PDF417 barcode enabled setting for preview"},"required":false,"description":"Override Croatian HUB3 PDF417 barcode enabled setting for preview","name":"hub3_qr_enabled","in":"query"},{"schema":{"type":"string","minLength":4,"maxLength":4,"pattern":"^[A-Z]{4}$","description":"Override HUB3 purpose code for preview"},"required":false,"description":"Override HUB3 purpose code for preview","name":"hub3_qr_purpose_code","in":"query"},{"schema":{"type":"string","pattern":"^HR\\d{2}$","description":"Override HUB3 Croatian reference model for preview"},"required":false,"description":"Override HUB3 Croatian reference model for preview","name":"hub3_qr_reference_model","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Delivery Note Data","required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PartialDeliveryNotePreview"},{"$ref":"#/components/schemas/CompleteDeliveryNotePreview"}]},"examples":{"Partial":{"value":{"items":[{"name":"Product Sample Kit","quantity":1,"price":5000}],"customer":{"name":"Acme Corp"}},"description":"Partial delivery note render with minimal data"},"Complete":{"value":{"items":[{"name":"Product Sample Kit","quantity":1,"price":5000,"taxes":[{"rate":22}]}],"customer":{"name":"Acme Corp","address":"123 Main St","city":"New York","post_code":"10001","country":"US"},"date":"2025-01-15","hide_prices":false},"description":"Complete delivery note render with full data"}}}}},"responses":{"200":{"description":"Rendered document (HTML)","content":{"text/html":{"schema":{"type":"string","description":"Fully formatted HTML document ready for display"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/delivery-notes/{id}/void":{"post":{"operationId":"voidDeliveryNote","summary":"Void a delivery note","description":"Void a delivery note for technical reasons (duplicate, error, etc.). Voiding marks the delivery note as invalid and prevents further modifications.","tags":["Delivery Notes"],"x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Void Delivery Note Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"description":"Technical reason for voiding (e.g., 'Duplicate delivery note', 'Technical error')","example":"Duplicate delivery note - issued in error"}}},"examples":{"Void Delivery Note":{"value":{"reason":"Duplicate delivery note created by mistake"}}}}}},"responses":{"200":{"description":"Voided Delivery Note","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryNote"},"examples":{"Voided Delivery Note":{"value":{"id":"del_abc123","voided_at":"2026-01-20T12:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/html":{"get":{"operationId":"renderDocumentHtml","summary":"Render HTML","description":"Render a saved document by its ID as HTML. The document type is automatically detected from the ID prefix (inv_, est_, cre_, adv_). The output is styled for professional presentation and optimized for display in web applications.","security":[{"Bearer":[]}],"tags":["Invoices","Estimates","CreditNotes","Advance Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","enum":["modern","classic","condensed","minimal","fashion"],"description":"Document template design to use. When not specified, uses the entity's configured template.","example":"modern"},"required":false,"description":"Document template design to use. When not specified, uses the entity's configured template.","name":"template","in":"query"},{"schema":{"type":["string","null"],"minLength":2,"maxLength":5,"description":"Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.","example":"sl-SI"},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.","name":"locale","in":"query"},{"schema":{"type":["string","null"],"minLength":2,"maxLength":5,"description":"Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.","example":"en-US"},"required":false,"description":"Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.","name":"language","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Rendered document (HTML)","content":{"text/html":{"schema":{"type":"string","description":"Fully formatted HTML document ready for display"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/pdf":{"get":{"operationId":"renderDocumentPdf","summary":"Render PDF","description":"Render a saved document by its ID as PDF. The document type is automatically detected from the ID prefix (inv_, est_, cre_, adv_). The output is styled for professional presentation and optimized for printing. Ideal for downloads and archival.","security":[{"Bearer":[]}],"tags":["Invoices","Estimates","CreditNotes","Advance Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","enum":["modern","classic","condensed","minimal","fashion"],"description":"Document template design to use. When not specified, uses the entity's configured template.","example":"modern"},"required":false,"description":"Document template design to use. When not specified, uses the entity's configured template.","name":"template","in":"query"},{"schema":{"type":["string","null"],"minLength":2,"maxLength":5,"description":"Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.","example":"sl-SI"},"required":false,"description":"Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.","name":"locale","in":"query"},{"schema":{"type":["string","null"],"minLength":2,"maxLength":5,"description":"Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.","example":"en-US"},"required":false,"description":"Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.","name":"language","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Rendered document (PDF)","content":{"application/pdf":{"schema":{"type":"string","format":"binary","description":"PDF document with multi-page support"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/next-number":{"get":{"operationId":"getNextDocumentNumber","summary":"Preview next document number","description":"Preview the next auto-generated document number for the specified type without incrementing the sequence. Useful for showing users what number will be assigned before creating a document.","security":[{"Bearer":[]}],"tags":["Documents","Invoices","Estimates","CreditNotes","Advance Invoices","Delivery Notes"],"parameters":[{"schema":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice","delivery_note"],"description":"Document type","example":"invoice"},"required":true,"description":"Document type","name":"type","in":"query"},{"schema":{"type":"string","description":"Optional business unit scope for unit-specific numbering sequences.","example":"business_unit_123"},"required":false,"description":"Optional business unit scope for unit-specific numbering sequences.","name":"business_unit_id","in":"query"},{"schema":{"type":"string","description":"Business premise name (FURS or FINA). If provided with electronic_device_name, returns fiscalization-format number.","example":"P1"},"required":false,"description":"Business premise name (FURS or FINA). If provided with electronic_device_name, returns fiscalization-format number.","name":"business_premise_name","in":"query"},{"schema":{"type":"string","description":"Electronic device name (FURS or FINA). Required if business_premise_name is provided. When provided, returns fiscalization-format number.","example":"E1"},"required":false,"description":"Electronic device name (FURS or FINA). Required if business_premise_name is provided. When provided, returns fiscalization-format number.","name":"electronic_device_name","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Next document number preview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NextDocumentNumber"},"examples":{"Standard format":{"description":"Standard document number preview","value":{"number":"2026-00042","furs":null}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/calculate":{"post":{"operationId":"calculateDocumentPreview","summary":"Preview document calculation","description":"Calculate document totals, taxes, and transaction type without creating the document. Useful for showing live totals in forms or validating data before submission.","security":[{"Bearer":[]}],"tags":["Documents","Invoices","Estimates","CreditNotes","Advance Invoices","Delivery Notes"],"parameters":[{"schema":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice","delivery_note"],"description":"Document type","example":"invoice"},"required":true,"description":"Document type","name":"type","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Document data to calculate","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateDocumentPreview"},"examples":{"Minimal":{"value":{"items":[{"name":"Web Development","quantity":10,"price":100,"taxes":[{"rate":22}]}]},"description":"Basic calculation with one item"}}}}},"responses":{"200":{"description":"Calculated document preview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentCalculation"},"examples":{"Minimal":{"value":{"items":[{"name":"Web Development","description":null,"type":null,"price":100,"gross_price":null,"quantity":10,"unit":null,"taxes":[{"name":"VAT","rate":22,"base":1000,"amount":220}],"discounts":[],"total":1000,"total_with_tax":1220,"total_converted":null,"total_with_tax_converted":null}],"total":1000,"total_with_tax":1220,"total_discount":0,"taxes":[{"name":"VAT","rate":22,"base":1000,"amount":220,"reverse_charge":false}],"transaction_type":"domestic","currency_code":"EUR","exchange_rate":null,"total_converted":null,"total_with_tax_converted":null,"rounding_correction":null,"vies":null},"description":"Basic calculation result"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/finalize":{"post":{"operationId":"finalizeDocument","summary":"Finalize a draft document","description":"Finalize a draft document by assigning a document number and running fiscalization (if applicable). Only draft documents can be finalized. After finalization, the document cannot be deleted.","security":[{"Bearer":[]}],"x-codegen-request-body-name":"data","tags":["Documents","Invoices","Estimates","CreditNotes","Advance Invoices","Delivery Notes"],"parameters":[{"schema":{"type":"string","description":"Document ID","example":"inv_clx1234567890"},"required":true,"description":"Document ID","name":"id","in":"path"},{"schema":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice","delivery_note"],"description":"Document type. Optional — automatically inferred from the document ID prefix.","example":"invoice"},"required":false,"description":"Document type. Optional — automatically inferred from the document ID prefix.","name":"type","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalizeDocumentBody"},"examples":{"FiscalizeWithFina":{"summary":"Finalize a Croatian draft with CIS fiscalization data","value":{"fina":{"business_premise_name":"PP1","electronic_device_name":"1","payment_type":"card"}}},"FiscalizeWithFurs":{"summary":"Finalize a Slovenian draft with FURS fiscalization data","value":{"furs":{"business_premise_name":"P1","electronic_device_name":"E1"}}}}}}},"responses":{"200":{"description":"Finalized document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericDocument"},"example":{"id":"inv_clx1234567890","number":"2025-001","is_draft":false,"date":"2025-01-15"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/fiscalize":{"post":{"operationId":"fiscalizeDocument","summary":"Retry document fiscalization","description":"Manually fiscalize a document. Retries failed FURS/FINA fiscalization, submits Slovenian FURS documents that were intentionally skipped and now need late fiscalization, or uses the old-FURS flow for no-status pre-FURS documents.","security":[{"Bearer":[]}],"x-codegen-request-body-name":"data","tags":["Documents","Invoices","CreditNotes","Advance Invoices"],"parameters":[{"schema":{"type":"string","description":"Document ID","example":"inv_clx1234567890"},"required":true,"description":"Document ID","name":"id","in":"path"},{"schema":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice","delivery_note"],"description":"Document type. Optional — automatically inferred from the document ID prefix.","example":"invoice"},"required":false,"description":"Document type. Optional — automatically inferred from the document ID prefix.","name":"type","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FiscalizeDocumentBody"},"examples":{"FursLateSubmit":{"summary":"Late FURS fiscalization","value":{"business_premise_name":"P1","electronic_device_name":"E1","operator_tax_number":"12345678","operator_label":"A.B.","foreign_operator":false}}}}}},"responses":{"200":{"description":"Document with updated fiscalization data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericDocument"},"example":{"id":"inv_clx1234567890","number":"2025-001","is_draft":false,"date":"2025-01-15"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/register-output":{"post":{"operationId":"registerDocumentOutput","summary":"Register fiscalized document output","description":"Atomically reserve the next output number for a successfully FURS- or FINA-fiscalized document. The first output is the unmarked original; output two and later are rendered with their number. Preview operations must not call this endpoint.","security":[{"Bearer":[]}],"tags":["Documents","Invoices","CreditNotes","Advance Invoices"],"parameters":[{"schema":{"type":"string","description":"Document ID","example":"inv_clx1234567890"},"required":true,"description":"Document ID","name":"id","in":"path"},{"schema":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice","delivery_note"],"description":"Document type. Optional — automatically inferred from the document ID prefix.","example":"invoice"},"required":false,"description":"Document type. Optional — automatically inferred from the document ID prefix.","name":"type","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Registered fiscalized document output","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FiscalizedOutputRegistration"},"example":{"print_count":2,"fiscalization_provider":"furs"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}":{"delete":{"operationId":"deleteDocument","summary":"Delete a draft document","description":"Delete a draft document. Only draft documents can be deleted. Finalized documents cannot be deleted - use void instead.","security":[{"Bearer":[]}],"tags":["Documents","Invoices","Estimates","CreditNotes","Advance Invoices","Delivery Notes"],"parameters":[{"schema":{"type":"string","description":"Document ID","example":"inv_clx1234567890"},"required":true,"description":"Document ID","name":"id","in":"path"},{"schema":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice","delivery_note"],"description":"Document type. Optional — automatically inferred from the document ID prefix.","example":"invoice"},"required":false,"description":"Document type. Optional — automatically inferred from the document ID prefix.","name":"type","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Document deleted successfully"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/restore":{"post":{"operationId":"restoreDocument","summary":"Restore a deleted document","description":"Restore a soft-deleted document from the trash. The document will be returned to its original state.","security":[{"Bearer":[]}],"tags":["Documents","Invoices","Estimates","CreditNotes","Advance Invoices","Delivery Notes"],"parameters":[{"schema":{"type":"string","description":"Document ID","example":"inv_clx1234567890"},"required":true,"description":"Document ID","name":"id","in":"path"},{"schema":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice","delivery_note"],"description":"Document type. Optional — automatically inferred from the document ID prefix.","example":"invoice"},"required":false,"description":"Document type. Optional — automatically inferred from the document ID prefix.","name":"type","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Restored document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericDocument"},"example":{"id":"inv_clx1234567890","number":"DRAFT-1234567890","is_draft":true,"deleted_at":null}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/permanent":{"delete":{"operationId":"permanentDeleteDocument","summary":"Permanently delete a document","description":"Permanently delete a soft-deleted document. Only documents in the trash can be permanently deleted. Only draft documents and estimates can be permanently deleted.","security":[{"Bearer":[]}],"tags":["Documents","Invoices","Estimates","CreditNotes","Advance Invoices","Delivery Notes"],"parameters":[{"schema":{"type":"string","description":"Document ID","example":"inv_clx1234567890"},"required":true,"description":"Document ID","name":"id","in":"path"},{"schema":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice","delivery_note"],"description":"Document type. Optional — automatically inferred from the document ID prefix.","example":"invoice"},"required":false,"description":"Document type. Optional — automatically inferred from the document ID prefix.","name":"type","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Document permanently deleted"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/send":{"post":{"operationId":"sendDocument","summary":"Send document via email","description":"Send a document via email. Automatically generates a public shareable link and optionally attaches the PDF. Supports markdown formatting and template variables in the email body.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Documents","Email"],"parameters":[{"schema":{"type":"string","description":"Document ID","example":"inv_clx1234567890"},"required":true,"description":"Document ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","format":"email","description":"Recipient email address","example":"customer@example.com"},"subject":{"type":"string","minLength":1,"maxLength":255,"description":"Email subject line. If not provided, uses default from entity settings.","example":"Your Invoice"},"body_text":{"type":"string","minLength":1,"description":"Email body text with optional markdown formatting and template variables ({document_number}, {customer_name}, {entity_name}, {invoice_link}).","example":"Please find your invoice attached.\n\nAccess it online: {invoice_link}"},"attach_pdf":{"type":"boolean","default":false,"description":"Whether to attach the document as a PDF.","example":false},"attach_eslog":{"type":"boolean","default":false,"description":"Whether to attach the document as e-SLOG 2.0 XML (Slovenian only).","example":false},"sandbox_skip_delivery":{"type":"boolean","default":false,"description":"Sandbox only. Build and validate the document email send flow without actually delivering the email.","example":false}},"required":["to"],"additionalProperties":false},"examples":{"Minimal":{"value":{"to":"customer@example.com"}},"Complete":{"value":{"to":"customer@example.com","subject":"Your Invoice #2025-001","body_text":"Please find your invoice attached.\n\nAccess it online: {invoice_link}","attach_pdf":true}}}}}},"responses":{"200":{"description":"Email sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string","description":"AWS SES message ID for tracking","example":"0000014d-3f45-4d2b-b470-0c8b9d1a4d6b@us-east-1.amazonses.com"},"status":{"type":"string","enum":["sent","queued","skipped"],"description":"Email send status","example":"sent"},"to":{"type":"string","description":"Recipient email address or comma-separated list of up to 4 recipient email addresses","example":"customer@example.com, accounting@example.com"},"subject":{"type":"string","description":"Email subject","example":"Your Invoice"},"shareable_link":{"type":"string","format":"uri","description":"Public URL for viewing the invoice online (if document_id was provided)","example":"http://localhost:3001/documents/shareable/inv_share_abc123..."},"sandbox_skip_delivery":{"type":"boolean","description":"True when sandbox testing used the send flow without delivering the email.","example":true}},"required":["message_id","status","to","subject"]},"examples":{"Success":{"value":{"message_id":"01234567-89ab-cdef-0123-456789abcdef","status":"sent","to":"customer@example.com","subject":"Invoice #2025-001","shareable_link":"https://app.example.com/documents/shareable/inv_share_abc123"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/activities":{"get":{"operationId":"getActivities","summary":"List activities","description":"Retrieve a paginated list of activities for the entity. Supports filtering by resource_type, resource_id, and action. Activities are ordered by created_at descending by default.","security":[{"Bearer":[]}],"tags":["Activities"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","created_at","resource_type","action","-id","-created_at","-resource_type","-action"]},{"type":"array","items":{"type":"string","enum":["id","created_at","resource_type","action","-id","-created_at","-resource_type","-action"]}}],"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, resource_type, resource_id, action, actor_type, created_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, resource_type, resource_id, action, actor_type, created_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"type":"string","description":"Filter by resource type (e.g., Invoice, Customer, Payment)","example":"Invoice"},"required":false,"description":"Filter by resource type (e.g., Invoice, Customer, Payment)","name":"resource_type","in":"query"},{"schema":{"type":"string","description":"Filter by specific resource ID","example":"inv_abc123"},"required":false,"description":"Filter by specific resource ID","name":"resource_id","in":"query"},{"schema":{"type":"string","description":"Filter by action type (e.g., created, updated, deleted, sent)","example":"created"},"required":false,"description":"Filter by action type (e.g., created, updated, deleted, sent)","name":"action","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of Activities","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique activity identifier","example":"act_abc123"},"entity_id":{"type":"string","description":"Entity that owns this activity","example":"ent_xyz789"},"resource_type":{"type":"string","description":"Type of resource (e.g., Invoice, Customer, Payment)","example":"Invoice"},"resource_id":{"type":"string","description":"ID of the resource","example":"inv_abc123"},"action":{"type":"string","description":"Action performed (e.g., created, updated, deleted, voided, sent)","example":"created"},"actor_type":{"type":"string","enum":["user","api_key","system","cron","webhook"],"description":"Who/what triggered the activity","example":"user"},"actor_id":{"type":["string","null"],"description":"User ID if actor_type is 'user'","example":"usr_abc123"},"actor_label":{"type":["string","null"],"description":"Display label (e.g., user email, 'Scheduled sync')","example":"user@example.com"},"details":{"type":["object","null"],"additionalProperties":{},"description":"Additional context about the activity","example":{"amount":100,"type":"bank_transfer"}},"created_at":{"type":"string","format":"date-time","description":"When the activity occurred","example":"2024-01-15T10:30:00.000Z"}},"required":["id","entity_id","resource_type","resource_id","action","actor_type","actor_id","actor_label","details","created_at"]}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"List activities":{"value":{"data":[{"id":"act_abc123","entity_id":"ent_xyz789","resource_type":"Invoice","resource_id":"inv_def456","action":"sent","actor_type":"user","actor_id":"usr_abc123","actor_label":"alex.carter@starward.example","details":{"to":"procurement@horizonlaunch.example","subject":"Invoice #INV-2024-001"},"created_at":"2024-01-15T14:30:00.000Z"},{"id":"act_def456","entity_id":"ent_xyz789","resource_type":"Invoice","resource_id":"inv_def456","action":"created","actor_type":"user","actor_id":"usr_abc123","actor_label":"alex.carter@starward.example","details":{},"created_at":"2024-01-15T10:00:00.000Z"}],"has_more":false,"next_cursor":null}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities/api-keys":{"get":{"operationId":"listEntityApiKeys","summary":"List entity API keys","description":"Retrieve all API keys for the current entity. Keys are masked for security.","security":[{"Bearer":[]}],"tags":["Entity API Keys"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of entity API keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityApiKeysList"},"examples":{"200":{"value":{"data":[{"id":"ek_sandbox_abc123def456789012345678abcd1234","entity_id":"ent_abc123def456","name":"Dashboard Access","environment":"sandbox","prefix_hint":"ek_sandbox_abc...234","created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z","expires_at":null}]}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createEntityApiKey","summary":"Create entity API key","description":"Create a new entity-scoped API key (ek_* prefix). This key can only access this specific entity.","security":[{"Bearer":[]}],"tags":["Entity API Keys"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Create Entity API Key Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"description":"Friendly name for the API key","example":"Production Integration Key"},"ttl":{"type":"integer","minimum":60,"description":"Time-to-live in seconds. The key expires after this duration. Minimum 60 seconds. Omit for a key that never expires.","example":86400}},"additionalProperties":false},"example":{"Create dashboard key":{"description":"Create an entity-scoped API key for dashboard access","value":{"name":"Dashboard Access"}},"Create short-lived key":{"description":"Create an entity-scoped API key that expires after 24 hours","value":{"name":"Embed SDK Key","ttl":86400}},"Create server integration key":{"description":"Create a long-lived entity-scoped key for a backend integration that should only operate inside the selected entity context.","value":{"name":"Production order sync"}},"Create preview session key":{"description":"Create a short TTL key for a temporary embedded dashboard or customer-support session.","value":{"name":"Customer portal preview","ttl":1800}}}}}},"responses":{"201":{"description":"Entity API key created. Save the full key - it won't be shown again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityApiKey"},"examples":{"201":{"value":{"id":"ek_sandbox_abc123def456789012345678abcd1234","entity_id":"ent_abc123def456","name":"Dashboard Access","environment":"sandbox","prefix_hint":"ek_sandbox_abc...234","created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z","expires_at":null}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities/api-keys/{id}":{"delete":{"operationId":"deleteEntityApiKey","summary":"Delete entity API key","description":"Permanently delete an entity API key. This action cannot be undone.","security":[{"Bearer":[]}],"tags":["Entity API Keys"],"parameters":[{"schema":{"type":"string","pattern":"^ek_(live|sandbox)_[0-9a-fA-F]{32}([0-9a-fA-F]{32})?$","description":"Entity API key ID (format: ek_{environment}_{hex})","example":"ek_sandbox_abc123def456789012345678abcd1234abc123def456789012345678abcd1234"},"required":true,"description":"Entity API key ID (format: ek_{environment}_{hex})","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Optional entity ID specifying which entity context to use for this operation.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Optional entity ID specifying which entity context to use for this operation.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"API key deleted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"examples":{"200":{"value":{"message":"API key deleted"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats/query":{"post":{"operationId":"queryEntityStats","summary":"Query entity stats (batch)","description":"Execute one or more aggregation queries on entity data in a single request.\n\nSend an array of 1-25 queries. Each query runs independently and results are returned in the same order.\n\n**Available tables**: invoices, estimates, credit_notes, advance_invoices, payments, customers, items\n\n**Metric types**: count, sum, avg, min, max\n\n**Virtual fields for group_by**:\n- `month` - Extract month from date (YYYY-MM)\n- `year` - Extract year from date (YYYY)\n- `overdue_bucket` - Invoice aging bucket (current, 1-30, 31-60, 61-90, 90+)\n\n**Example — single query (monthly revenue)**:\n```json\n[{\n  \"metrics\": [{ \"type\": \"sum\", \"field\": \"total_with_tax\", \"alias\": \"revenue\" }],\n  \"table\": \"invoices\",\n  \"date_from\": \"2024-01-01\",\n  \"filters\": { \"is_draft\": false, \"voided_at\": null },\n  \"group_by\": [\"month\"]\n}]\n```\n\n**Example — multi query (dashboard counts)**:\n```json\n[\n  { \"metrics\": [{ \"type\": \"count\", \"alias\": \"total\" }], \"table\": \"invoices\" },\n  { \"metrics\": [{ \"type\": \"count\", \"alias\": \"total\" }], \"table\": \"customers\" }\n]\n```","security":[{"Bearer":[]}],"tags":["Entity Stats"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Batch Stats Query Request","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsQueryBatchRequest"},"examples":{"Single Query — Monthly Revenue":{"value":[{"metrics":[{"type":"sum","field":"total_with_tax","alias":"revenue"}],"table":"invoices","date_from":"2024-01-01","filters":{"is_draft":false,"voided_at":null},"group_by":["month"]}],"description":"Single query: sum revenue by month for all finalized invoices"},"Multi Query — Dashboard Counts":{"value":[{"metrics":[{"type":"count","alias":"total"}],"table":"invoices"},{"metrics":[{"type":"count","alias":"total"}],"table":"estimates"},{"metrics":[{"type":"count","alias":"total"}],"table":"customers"}],"description":"Multiple queries in one request: count invoices, estimates, and customers"},"Revenue by customer":{"value":[{"metrics":[{"type":"sum","field":"total_with_tax","alias":"revenue"}],"table":"invoices","date_from":"2024-01-01","date_to":"2024-12-31","filters":{"is_draft":false,"voided_at":null},"group_by":["customer_id"]}],"description":"Group invoice revenue by customer for dashboard widgets."},"Open receivables":{"value":[{"metrics":[{"type":"sum","field":"total_due","alias":"amount_due"}],"table":"invoices","filters":{"paid_in_full":false,"is_draft":false,"voided_at":null}}],"description":"Sum unpaid finalized invoice balances for an accounts-receivable widget."}}}}},"responses":{"200":{"description":"Batch Stats Query Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatsQueryBatchResponse"},"examples":{"Single Query — Monthly Revenue":{"value":[{"query":{"table":"invoices","date_from":"2024-01-01","date_to":null,"group_by":["month"]},"data":[{"month":"2024-01","revenue":5000},{"month":"2024-02","revenue":7500}],"row_count":2}],"description":"Single query result wrapped in array"},"Multi Query — Dashboard Counts":{"value":[{"query":{"table":"invoices","date_from":null,"date_to":null,"group_by":null},"data":[{"total":42}],"row_count":1},{"query":{"table":"estimates","date_from":null,"date_to":null,"group_by":null},"data":[{"total":15}],"row_count":1},{"query":{"table":"customers","date_from":null,"date_to":null,"group_by":null},"data":[{"total":28}],"row_count":1}],"description":"Multiple query results in same order as requests"},"Revenue by customer":{"value":[{"query":{"table":"invoices","date_from":"2024-01-01","date_to":"2024-12-31","group_by":["customer_id"]},"data":[{"customer_id":"cus_6595a27b5d35015c3ef0c3fd","revenue":8400},{"customer_id":"cus_6595a27b5d35015c3ef0c3fe","revenue":3150}],"row_count":2}],"description":"Revenue grouped by a supported invoice stats field."},"Open receivables":{"value":[{"query":{"table":"invoices","date_from":null,"date_to":null,"group_by":null},"data":[{"amount_due":2750}],"row_count":1}],"description":"Outstanding finalized invoice balance."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities/users":{"get":{"operationId":"getEntityUsers","summary":"List entity users","description":"Retrieve all users who have access to the current entity, including their roles.","security":[{"Bearer":[]}],"tags":["Entity Users"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of entity users","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityUsersList"},"examples":{"Example":{"value":{"data":[{"user_id":"user_abc123","entity_id":"ent_xyz789","role":"admin","email":"admin@example.com","name":"Morgan Vega","invited_by_user_id":null,"created_at":"2024-01-01T00:00:00.000Z"},{"user_id":"user_def456","entity_id":"ent_xyz789","role":"editor","email":"editor@example.com","name":"Riley Nova","invited_by_user_id":"user_abc123","created_at":"2024-01-15T00:00:00.000Z"}]},"description":"List of users with access to the entity"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addEntityUser","summary":"Add user to entity","description":"Add an existing white-label user for this account to the entity or send an invitation. Existing account users must accept the invitation so they receive separate entity-user access.","security":[{"Bearer":[]}],"tags":["Entity Users"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Add Entity User Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address of the user to add or invite","example":"user@example.com"},"role":{"type":"string","enum":["viewer","editor","admin"],"default":"editor","description":"Role to assign to the user","example":"editor"},"send_invite":{"type":"boolean","default":true,"description":"Whether to send an invitation email (only applies to new users)"}},"required":["email"],"additionalProperties":false},"examples":{"Add editor":{"value":{"email":"newuser@example.com","role":"editor","send_invite":true},"description":"Add a new user as editor with invitation email"},"Add viewer":{"value":{"email":"viewer@example.com","role":"viewer"},"description":"Add a user as viewer (default sends invite)"},"Add existing user silently":{"value":{"email":"ops@example.com","role":"editor","send_invite":false},"description":"Grant access to an existing user without sending another invitation email"}}}}},"responses":{"201":{"description":"User added or invitation sent","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/EntityUser"},{"type":"object","properties":{"message":{"type":"string"},"invitation_id":{"type":"string"}},"required":["message","invitation_id"]}]},"examples":{"User added":{"value":{"user_id":"user_new123","entity_id":"ent_xyz789","role":"editor","email":"newuser@example.com","name":"Alex Carter","invited_by_user_id":"user_abc123","created_at":"2024-01-20T00:00:00.000Z"},"description":"Existing user added to entity"},"Invitation sent":{"value":{"message":"Invitation sent","invitation_id":"einv_abc123"},"description":"Invitation sent to new user"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities/users/access":{"get":{"operationId":"getEntityUsersAccess","summary":"Get entity user access state","description":"Return the current user's account/entity access state for entity-user management. This is separate from country or compliance feature availability.","security":[{"Bearer":[]}],"tags":["Entity Users"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Current entity-user access state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityUsersAccess"},"examples":{"Account admin":{"value":{"account_id":"acc_507f1f77bcf86cd799439011","account_role":"admin","entity_id":"ent_507f1f77bcf86cd799439011","entity_role":null,"is_account_admin":true,"is_entity_admin":false,"account_admin_override":true,"can_manage_entity_users":true,"enforce_entity_admin_preservation":false},"description":"Top-level account admin can manage entity users without final-admin preservation."},"Entity admin":{"value":{"account_id":"acc_507f1f77bcf86cd799439011","account_role":null,"entity_id":"ent_507f1f77bcf86cd799439011","entity_role":"admin","is_account_admin":false,"is_entity_admin":true,"account_admin_override":false,"can_manage_entity_users":true,"enforce_entity_admin_preservation":true},"description":"Entity-scoped admin can manage entity users but must preserve one entity admin."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities/users/{user_id}":{"patch":{"operationId":"updateEntityUserRole","summary":"Update user role","description":"Update a user's role on the entity. Roles: viewer (read-only), editor (read+write), admin (full access).","security":[{"Bearer":[]}],"tags":["Entity Users"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"user_id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Optional entity ID specifying which entity context to use for this operation.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Optional entity ID specifying which entity context to use for this operation.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Entity User Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["viewer","editor","admin"],"description":"New role to assign to the user","example":"editor"}},"required":["role"],"additionalProperties":false},"examples":{"Promote to admin":{"value":{"role":"admin"},"description":"Promote user to admin role"},"Demote to viewer":{"value":{"role":"viewer"},"description":"Change user role to viewer (read-only)"}}}}},"responses":{"200":{"description":"Updated entity user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityUser"},"examples":{"Example":{"value":{"user_id":"user_def456","entity_id":"ent_xyz789","role":"admin","email":"editor@example.com","name":"Riley Nova","invited_by_user_id":"user_abc123","created_at":"2024-01-15T00:00:00.000Z"},"description":"User with updated role"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"removeEntityUser","summary":"Remove user from entity","description":"Remove a user's access to the entity. This does not delete the user account.","security":[{"Bearer":[]}],"tags":["Entity Users"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"user_id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Optional entity ID specifying which entity context to use for this operation.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Optional entity ID specifying which entity context to use for this operation.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"User removed from entity","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"examples":{"Example":{"value":{"message":"User removed from entity"},"description":"Confirmation of user removal"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities/users/{user_id}/token":{"post":{"operationId":"generateEntityUserToken","summary":"Generate user access token","description":"Generate a delegated SSO access token for a WL user to enable SSO-like redirect. Requires an account API key or a non-impersonated account owner/admin user token; entity API keys, entity-only roles, and account members are rejected. The token has the standard one-year session TTL but cannot authorize user-presence-sensitive operations such as account deletion, so callers must treat issuance as a privileged account-level operation.","security":[{"Bearer":[]}],"tags":["Entity Users"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"user_id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Optional entity ID specifying which entity context to use for this operation.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Optional entity ID specifying which entity context to use for this operation.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Access token generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateUserTokenResponse"},"examples":{"Example":{"value":{"id":"session_e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","user_id":"user_def456","ttl":31536000,"scope":null,"created_at":"2024-01-20T10:00:00.000Z","updated_at":"2024-01-20T10:00:00.000Z","entity_id":"ent_xyz789"},"description":"Access token for SSO-like redirect"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities/invitations":{"get":{"operationId":"listEntityInvitations","summary":"List entity invitations","description":"Retrieve all invitations for the current entity, including pending, accepted, and expired.","security":[{"Bearer":[]}],"tags":["Entity Invitations"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of entity invitations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityInvitationsList"},"examples":{"200":{"value":{"data":[{"id":"einv_abc123def456789012345678","entity_id":"ent_abc123def456","email":"newuser@example.com","name":"Alex Carter","role":"editor","status":"pending","invited_by":"user_xyz789","expires_at":"2024-01-08T00:00:00.000Z","created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}]}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities/invitations/{id}":{"get":{"operationId":"getEntityInvitation","summary":"Get entity invitation","description":"Retrieve details of a specific invitation.","security":[{"Bearer":[]}],"tags":["Entity Invitations"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Optional entity ID specifying which entity context to use for this operation.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Optional entity ID specifying which entity context to use for this operation.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Invitation details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityInvitation"},"examples":{"200":{"value":{"id":"einv_abc123def456789012345678","entity_id":"ent_abc123def456","email":"newuser@example.com","name":"Alex Carter","role":"editor","status":"pending","invited_by":"user_xyz789","expires_at":"2024-01-08T00:00:00.000Z","created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"cancelEntityInvitation","summary":"Cancel invitation","description":"Cancel a pending invitation. Cannot cancel already accepted invitations.","security":[{"Bearer":[]}],"tags":["Entity Invitations"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Optional entity ID specifying which entity context to use for this operation.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Optional entity ID specifying which entity context to use for this operation.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Invitation cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"examples":{"200":{"value":{"message":"Invitation cancelled"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities/invitations/{id}/resend":{"post":{"operationId":"resendEntityInvitation","summary":"Resend invitation","description":"Resend an invitation email with a new token and extended expiry.","security":[{"Bearer":[]}],"tags":["Entity Invitations"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Optional entity ID specifying which entity context to use for this operation.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Optional entity ID specifying which entity context to use for this operation.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Invitation resent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendInvitationResponse"},"examples":{"200":{"value":{"message":"Invitation resent"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invitations/preview":{"get":{"operationId":"previewEntityInvitation","summary":"Preview invitation","description":"Preview an entity invitation by token before accepting it.","tags":["Entity Invitations"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Invitation token from the invitation email","example":"einvt_abc123xyz789"},"required":true,"description":"Invitation token from the invitation email","name":"token","in":"query"}],"responses":{"200":{"description":"Invitation preview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityInvitationPreview"},"example":{"email":"invitee@example.com","entity_name":"Starward Equipment Co.","existing_user":false,"role":"member","status":"pending","expires_at":"2026-05-13T12:00:00.000Z"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invitations/accept":{"post":{"operationId":"acceptEntityInvitation","summary":"Accept invitation","description":"Accept an entity invitation by providing user details. Creates or links a white-label user for the invited entity account and grants entity access. Returns an access token for immediate use.","tags":["Entity Invitations"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Invitation token from the invitation email","example":"einvt_abc123xyz789"},"required":true,"description":"Invitation token from the invitation email","name":"token","in":"query"}],"requestBody":{"description":"Accept invitation details","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"description":"Name of the user accepting the invitation","example":"John Doe"},"password":{"type":"string","minLength":1,"description":"Password for the new user account, or current password for an existing invited user","example":"Securepassword123!"}},"required":["password"],"additionalProperties":false},"example":{"Accept with signup":{"description":"Accept invitation and create account","value":{"token":"abc123def456","name":"Alex Carter","password":"SecurePass123!"}},"Accept existing user":{"description":"Accept an invitation for an already authenticated or existing user","value":{"token":"abc123def456"}}}}}},"responses":{"200":{"description":"Invitation accepted, user created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptInvitationResponse"},"examples":{"200":{"value":{"user_id":"user_abc123","entity_id":"ent_xyz789","access_token":"token_live_abc123"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities":{"post":{"operationId":"createEntity","summary":"Create a new entity","description":"Create a new legal entity (business, organization, or sole proprietor). Entities are the core organizational unit that owns customers, invoices, and items. Each entity can have custom number formatting for invoices and other settings.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Entities"],"parameters":[{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"requestBody":{"description":"Create Entity Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"address":{"type":["string","null"],"maxLength":500},"address_2":{"type":["string","null"],"maxLength":500},"post_code":{"type":["string","null"],"maxLength":20},"city":{"type":["string","null"],"maxLength":100},"state":{"type":["string","null"],"maxLength":100},"country":{"type":"string","maxLength":100},"country_code":{"type":["string","null"],"minLength":2,"maxLength":2},"currency_code":{"type":["string","null"],"maxLength":3},"locale":{"type":["string","null"],"maxLength":20},"timezone":{"type":"string","maxLength":100,"description":"IANA timezone used for business calendar dates, including recurring document issue dates.","example":"Europe/Ljubljana"},"tax_number":{"type":["string","null"],"maxLength":50},"tax_number_2":{"type":["string","null"],"maxLength":50},"company_number":{"type":["string","null"],"maxLength":50},"phone":{"type":["string","null"],"maxLength":50},"email":{"type":["string","null"],"maxLength":255},"website":{"type":["string","null"],"maxLength":500},"fiscal_region_code":{"type":["string","null"],"maxLength":10},"starting_capital":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"environment":{"type":"string","enum":["live","sandbox"]},"is_tax_subject":{"type":"boolean"},"is_enabled":{"type":"boolean","description":"Whether the entity is enabled. Disabled entities cannot create documents (invoices, estimates, etc.) but all data remains accessible and settings can be updated."},"settings":{"type":"object","properties":{"pdf_template":{"type":["string","null"],"enum":["modern","classic","condensed","minimal","fashion","timeless_modern_full_data",null],"description":"Default PDF template for document rendering. Defaults to 'modern' if not set.","example":"modern"},"number_formats":{"type":["object","null"],"properties":{"invoice":{"type":["string","null"]},"estimate":{"type":["string","null"]},"credit_note":{"type":["string","null"]},"advance_invoice":{"type":["string","null"]},"delivery_note":{"type":["string","null"]},"expense":{"type":["string","null"]}}},"unit_number_formats":{"type":["object","null"],"properties":{"invoice":{"type":["string","null"]},"estimate":{"type":["string","null"]},"credit_note":{"type":["string","null"]},"advance_invoice":{"type":["string","null"]},"delivery_note":{"type":["string","null"]}}},"number_sequence_starts":{"anyOf":[{"$ref":"#/components/schemas/NumberSequenceStarts"},{"type":"null"}]},"unit_number_sequence_starts":{"anyOf":[{"$ref":"#/components/schemas/UnitNumberSequenceStarts"},{"type":"null"}]},"primary_color":{"type":["string","null"],"pattern":"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"},"logo_scale_percent":{"type":["integer","null"],"minimum":30,"maximum":100,"description":"Scale the PDF logo size as a percentage of the template default size. 100 keeps the original size.","example":70},"has_logo":{"type":["boolean","null"]},"has_signature":{"type":["boolean","null"]},"default_invoice_due_days":{"type":["integer","null"],"exclusiveMinimum":0,"description":"Default number of days until invoice is due (from invoice date)","example":30},"default_estimate_valid_days":{"type":["integer","null"],"exclusiveMinimum":0,"description":"Default number of days until estimate expires (from estimate date)","example":30},"email":{"type":["string","null"],"format":"email","description":"Sender email address used for outgoing document and reminder emails. Falls back to the platform default sender when not set. Set to null to clear.","example":"billing@example.com"},"email_defaults":{"type":["object","null"],"properties":{"invoice_subject":{"type":["string","null"],"description":"Default subject line for invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_due_date}, {document_total}, {document_currency}","example":"Invoice {document_number} from {entity_name}"},"invoice_body":{"type":["string","null"],"description":"Default body text for invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_due_date}, {document_total}, {document_currency}","example":"Please find invoice {document_number} attached.\nDue date: {document_due_date}."},"estimate_subject":{"type":["string","null"],"description":"Default subject line for estimate emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_valid_until}, {document_total}, {document_currency}","example":"Estimate {document_number} from {entity_name}"},"estimate_body":{"type":["string","null"],"description":"Default body text for estimate emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_valid_until}, {document_total}, {document_currency}","example":"Please find estimate {document_number} attached.\nValid until: {document_valid_until}."},"credit_note_subject":{"type":["string","null"],"description":"Default subject line for credit note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Credit note {document_number} from {entity_name}"},"credit_note_body":{"type":["string","null"],"description":"Default body text for credit note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Please find credit note {document_number} attached."},"advance_invoice_subject":{"type":["string","null"],"description":"Default subject line for advance invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Advance invoice {document_number} from {entity_name}"},"advance_invoice_body":{"type":["string","null"],"description":"Default body text for advance invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Please find advance invoice {document_number} attached."},"delivery_note_subject":{"type":["string","null"],"description":"Default subject line for delivery note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Delivery note {document_number} from {entity_name}"},"delivery_note_body":{"type":["string","null"],"description":"Default body text for delivery note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Please find delivery note {document_number} attached."}}},"default_invoice_note":{"type":["string","null"],"description":"Default note for new invoices. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Payment due by {document_due_date}. Please reference invoice {document_number} when making payment."},"default_invoice_payment_terms":{"type":["string","null"],"description":"Default payment terms for new invoices. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Please remit payment using the bank details shown on the document."},"default_estimate_note":{"type":["string","null"],"description":"Default note for new estimates. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_valid_until}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"This estimate is valid until {document_valid_until}."},"default_estimate_payment_terms":{"type":["string","null"],"description":"Default payment terms for new estimates. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_valid_until}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Payment due upon acceptance."},"default_credit_note_note":{"type":["string","null"],"description":"Default note for new credit notes. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Credit note for invoice {document_number}."},"default_credit_note_payment_terms":{"type":["string","null"],"description":"Default payment terms for new credit notes. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Credit will be applied to your account."},"default_advance_invoice_note":{"type":["string","null"],"description":"Default note for new advance invoices. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Advance payment requested for {document_number}."},"default_delivery_note_note":{"type":["string","null"],"description":"Default note for new delivery notes. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Goods delivered under delivery note {document_number}."},"document_footer":{"type":["string","null"],"maxLength":500,"description":"Footer text for PDF documents. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"{entity_name} | Due Date: {document_due_date} | Invoice #{document_number}"},"default_document_signature":{"type":["string","null"],"description":"Default signature text for all new documents. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"{entity_name}"},"translations":{"anyOf":[{"$ref":"#/components/schemas/EntitySettingsTranslations"},{"type":"null"}],"description":"Translated default document-facing settings keyed by full supported locales. Used when new documents inherit default texts and when document defaults are rendered in an explicit non-default language."},"calculation":{"anyOf":[{"$ref":"#/components/schemas/CalculationSettings"},{"type":"null"}],"description":"Document calculation defaults. Controls whether newly calculated documents use the standard B2B net-first model or the B2C gross-discount model by default."},"slovenia":{"anyOf":[{"$ref":"#/components/schemas/SloveniaEntitySettings"},{"type":"null"}],"description":"Slovenia-specific tax profile used by yearly eDavki exports and future Slovenia-specific reporting flows."},"furs":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Whether FURS fiscalization is enabled for this entity","example":true},"default_skip_fiscalization":{"type":"boolean","default":false,"description":"Whether new FURS-capable documents should start with fiscalization skipped by default. Payment type rules still override this and require fiscalization for non-bank-transfer payments.","example":false},"numbering_strategy":{"type":"string","enum":["B","C"],"description":"Numbering strategy: B (device-level) or C (centralized). Optional - can be set per-premise.","example":"C"},"operator_tax_number":{"type":"string","description":"Operator tax number for this entity (used when creating invoices via API key)","example":"12345678"},"operator_label":{"type":"string","description":"Operator label/name for this entity","example":"Cash Register 1"},"foreign_operator":{"type":"boolean","description":"Whether the operator is a foreign legal entity","example":false},"environment":{"type":"string","enum":["test","production"],"description":"FURS environment override (test or production). When omitted, derived from entity environment.","example":"test"}},"description":"FURS (Slovenia) fiscalization settings. Certificate data is stored separately via the certificate upload endpoint."},"fina":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Whether CIS (FINA) fiscalization is enabled for this entity","example":true},"operator_oib":{"type":"string","minLength":11,"maxLength":11,"description":"OIB of the operator (11 digits). Used when creating invoices via API key.","example":"12345678901"},"operator_label":{"type":"string","description":"Operator label/name for this entity","example":"Cash Register 1"},"u_sust_pdv":{"type":"boolean","default":true,"description":"Whether the entity is in the PDV (VAT) system. Most businesses are.","example":true},"numbering_sequence":{"type":"string","enum":["N","P"],"default":"P","description":"Numbering sequence: P (per premise) or N (per device)","example":"P"},"unified_numbering":{"type":["boolean","null"],"description":"When enabled (default: true), all documents use the same FINA numbering sequence regardless of transaction type (domestic/non-domestic)","example":true},"certificate_expiry":{"type":"string","description":"Certificate expiry date (ISO 8601 format)","example":"2026-12-31T23:59:59.000Z"}},"description":"FINA (Croatia) CIS fiscalization settings. Required for Croatian B2C invoicing. Certificate data is stored separately via the certificate upload endpoint."},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtEntitySettings"},{"type":"null"}],"description":"Portugal operator defaults used for PT document creation when request-level or user-level PT operator data is not available."},"tax_rules":{"anyOf":[{"$ref":"#/components/schemas/TaxRules"},{"type":"null"}],"description":"Tax rules engine settings. Controls automatic tax behaviors based on entity location and transaction characteristics (VIES validation, reverse charge, export tax removal). Defaults are set automatically based on entity country. Set to null for non-EU entities."},"overdue_notifications":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Enable automatic overdue invoice notification emails to customers","example":true},"threshold_days":{"type":"array","items":{"type":"integer","exclusiveMinimum":0},"default":[7,14,30],"description":"Days overdue when notification emails are sent (exact day match). Email is triggered when any invoice hits these thresholds.","example":[7,14,30]},"email_subject":{"type":["string","null"],"deprecated":true,"description":"Deprecated legacy content field. Use settings.payment_reminders.email_subject for reminder email content. Automatic reminder scheduling remains configured under overdue_notifications.","example":"Payment reminder from {entity_name}"},"email_body":{"type":["string","null"],"deprecated":true,"description":"Deprecated legacy content field. Use settings.payment_reminders.email_body for reminder email content. Automatic reminder scheduling remains configured under overdue_notifications.","example":"Hello,\n\nThe invoices below are overdue. Please arrange payment of {total_amount} at your earliest convenience.\n\n{invoice_list}\n\n{payment_instructions}\n\nIf you have already paid, please disregard this reminder.\n\nBest regards,"}},"description":"Settings for automatic overdue invoice notification emails to customers"},"payment_reminders":{"type":["object","null"],"properties":{"email_subject":{"type":["string","null"],"description":"Default subject for manual and automatic payment reminder emails. Available variables: {customer_name}, {entity_name}, {overdue_count}","example":"Payment reminder from {entity_name}"},"email_body":{"type":["string","null"],"description":"Default body for manual and automatic payment reminder emails. Available variables: {customer_name}, {entity_name}, {invoice_list}, {payment_instructions}, {total_amount}, {entity_email}, {overdue_count}. Missing invoice list or payment instructions blocks are appended automatically.","example":"Hello,\n\nThe invoices below are overdue. Please arrange payment of {total_amount} at your earliest convenience.\n\n{invoice_list}\n\n{payment_instructions}\n\nIf you have already paid, please disregard this reminder.\n\nBest regards,"},"payment_instructions":{"type":["string","null"],"description":"Default payment instructions for payment reminder emails. Supports bank placeholders: {iban}, {bic}, {bank_name}, {account_number}, {routing_number}, {sort_code}","example":"Please remit payment to IBAN {iban}."}},"description":"Shared content defaults for manual and automatic payment reminder emails. Automatic reminder scheduling remains configured under overdue_notifications."},"upn_qr":{"anyOf":[{"$ref":"#/components/schemas/UpnQrSettings"},{"type":"null"}],"description":"UPN QR payment slip settings (Slovenia only). Displays payment QR code on invoices for easy bank transfers."},"epc_qr":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","description":"Whether EPC QR code is enabled on EUR invoices (SEPA countries)","example":true}},"required":["enabled"],"description":"EPC QR code settings (SEPA countries). Displays SEPA credit transfer QR code on EUR invoices for easy bank payment."},"hub3_qr":{"anyOf":[{"$ref":"#/components/schemas/Hub3QrSettings"},{"type":"null"}],"description":"Croatian HUB3 PDF417 payment barcode settings. Displays the barcode used by Croatian banking apps on EUR invoices."},"bank_accounts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/EntityBankAccount"},"description":"Bank accounts for receiving payments. The first account with is_default=true (or first in list) is used for new invoices."},"eslog_validation_enabled":{"type":["boolean","null"],"description":"Enable e-SLOG 2.0 validation for documents. Only applicable for Slovenian entities (country_code = 'SI'). When enabled, documents are validated against e-SLOG 2.0 requirements and can be exported as e-SLOG XML if valid.","example":true},"ujp_validation_with_eslog_enabled":{"type":["boolean","null"],"description":"When true for Slovenian entities, API/UI document create flows that enable e-SLOG also validate UJP package/envelope requirements for supported document types. Web may expose UJP download as a secondary e-SLOG dropdown action when current UJP validation is valid.","example":false},"xrechnung":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Enable German XRechnung XML validation by default and export actions for finalized German invoices and credit notes. Only applies to German entities whose country rules include e_invoicing. Final create/update calls only fail on validation errors when the request xrechnung.validation_required flag is true; XRechnung export always requires a current valid validation result.","example":true}},"description":"German XRechnung XML export settings. Separate from Peppol sending/onboarding settings and separate from document xrechnung validation state."},"zugferd":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Enable German ZUGFeRD/Factur-X validation by default and export actions for finalized German invoices and credit notes. Only applies to German entities whose country rules include e_invoicing. Final create/update calls only fail on validation errors when the request zugferd.validation_required flag is true; ZUGFeRD export always requires a current valid validation result.","example":true}},"description":"German ZUGFeRD/Factur-X PDF export settings. Separate from Peppol sending/onboarding settings and separate from document zugferd validation state."},"delivery_note_hide_prices":{"type":["boolean","null"],"description":"Default hide_prices setting for new delivery notes. When true, prices and totals are hidden (packing list mode).","example":false},"credit_note_negative_values":{"type":["boolean","null"],"description":"When true (default), credit note PDFs display line item quantities and totals as negative values while keeping prices positive. Zero quantities and totals stay unsigned. Set to false to show quantities and totals as positive.","example":true},"show_payment_amounts":{"type":["boolean","null"],"description":"When true, rendered document payment/refund sections show the payment amount next to each payment type. Defaults to false, which shows only the payment or refund type.","example":false},"receipt_note":{"type":["string","null"],"maxLength":500,"description":"Default note printed on thermal receipts."},"receipt_footer":{"type":["string","null"],"maxLength":500,"description":"Default footer text printed on thermal receipts (e.g. IBAN, thank-you message)."},"receipt_signature":{"type":["string","null"],"maxLength":200,"description":"Default signature / issuer label printed on thermal receipts."},"tax_clause_defaults":{"anyOf":[{"$ref":"#/components/schemas/TaxClauseDefaults"},{"type":"null"}],"description":"Default tax clauses per transaction type. Auto-applied to documents based on transaction type determination. Supports template variables: {entity_name}, {customer_name}, {document_number}, etc."},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/EInvoicingEntitySettings"},{"type":"null"}],"description":"E-invoicing settings for sending documents via the Peppol network. Requires verified entity enrollment before documents can be sent electronically."},"revenue_recognition":{"anyOf":[{"$ref":"#/components/schemas/RevenueRecognitionSettings"},{"type":"null"}],"description":"Deferred revenue and accrued revenue settings. When enabled, finalized eligible sales documents generate monthly recognition entries from their service periods."},"expense_recognition":{"anyOf":[{"$ref":"#/components/schemas/ExpenseRecognitionSettings"},{"type":"null"}],"description":"Expense recognition settings. Finalized expenses can generate monthly recognition entries from service periods."}},"description":"Entity settings"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"required":["name","country"],"additionalProperties":false},"examples":{"Minimal":{"value":{"name":"Starward Equipment Co.","country":"United States"},"description":"Minimal entity with required fields (name and country). Country will be resolved to country_code."},"EU Entity":{"value":{"name":"Orbital Systems GmbH","address":"Musterstraße 123","post_code":"10115","city":"Berlin","country":"Germany","tax_number":"DE123456789","tax_number_2":"12/345/67890","company_number":"HRB 12345","metadata":{"industry":"Software"}},"description":"EU entity with VAT number. EU entities get default tax_rules with VIES validation enabled."},"US entity with tax lookup":{"value":{"name":"Starward Equipment Co.","address":"1 Launchpad Way","post_code":"32920","city":"Cape Canaveral","state":"FL","country":"United States","country_code":"US","locale":"en-US"},"description":"US entity using US locale/currency defaults. The response country_rules advertises supported helper features such as tax-rate lookup and e-invoicing."},"Slovenian entity for compliance":{"value":{"name":"Vzorec Storitve d.o.o.","address":"Poslovna cesta 10","post_code":"1000","city":"Ljubljana","country":"Slovenia","country_code":"SI","tax_number":"SI12345678","company_number":"1234567000","locale":"sl-SI","currency_code":"EUR"},"description":"Slovenian entity with identifiers used by FURS, e-SLOG, UPN QR, KIR, and yearly tax-report flows."},"With translations":{"value":{"name":"Orbital Systems GmbH","country":"Germany","locale":"de-DE","settings":{"translations":{"default_invoice_note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"document_footer":{"de-DE":"Orbital Systems GmbH"},"default_document_signature":{"de-DE":"Orbital Systems Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Anbei finden Sie die Rechnung {document_number}."}},"tax_clause_defaults":{"intra_eu_b2b":{"de-DE":"Steuerschuldnerschaft des Leistungsempfaengers."}}}}},"description":"Entity with translated default document and email content"},"Complete":{"value":{"name":"Orbital Systems GmbH","address":"Musterstraße 123","address_2":"Building A","post_code":"10115","city":"Berlin","country":"Germany","tax_number":"DE123456789","company_number":"HRB 12345","metadata":{"industry":"Technology","size":"Medium"},"settings":{"translations":{"default_invoice_note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"document_footer":{"de-DE":"Orbital Systems GmbH"},"default_document_signature":{"de-DE":"Orbital Systems Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Anbei finden Sie die Rechnung {document_number}."}},"tax_clause_defaults":{"intra_eu_b2b":{"de-DE":"Steuerschuldnerschaft des Leistungsempfaengers."}}}}},"description":"Complete EU entity with all optional fields. EU entities get tax_rules with VIES validation and configurable reverse charge."}}}}},"responses":{"201":{"description":"Created Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"},"examples":{"Minimal":{"value":{"id":"ent_6595a27b5d35015c3ef0c3fd","name":"Starward Equipment Co.","address":null,"address_2":null,"post_code":null,"city":null,"state":null,"country":"United States","country_code":"US","currency_code":"USD","locale":"en-US","tax_number":null,"tax_number_2":null,"company_number":null,"email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":true,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"{yyyy}-{nnnnn}","delivery_note":"{yyyy}-{nnnnn}","expense":"{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Invoice {document_number} from {entity_name}","invoice_body":"Please find invoice {document_number} attached.\nDue date: {document_due_date}.\n\n[View document]({invoice_link})","estimate_subject":"{document_label} {document_number} from {entity_name}","estimate_body":"Please find {document_label} {document_number} attached.\nValid until: {document_valid_until}.\n\n[View document]({invoice_link})","credit_note_subject":"Credit note {document_number} from {entity_name}","credit_note_body":"Please find credit note {document_number} attached.\n\n[View document]({invoice_link})","advance_invoice_subject":"Advance invoice {document_number} from {entity_name}","advance_invoice_body":"Please find advance invoice {document_number} attached.\n\n[View document]({invoice_link})","delivery_note_subject":"Delivery note {document_number} from {entity_name}","delivery_note_body":"Please find delivery note {document_number} attached.\n\n[View document]({invoice_link})"},"default_invoice_due_days":30,"default_invoice_payment_terms":null,"default_estimate_valid_days":30,"document_footer":"{entity_name}","default_document_signature":"{entity_name}","overdue_notifications":{"enabled":false,"threshold_days":[7,14,30],"email_subject":"Payment reminder from {entity_name}","email_body":"Hello,\n\nThe invoices below are overdue. Please arrange payment of {total_amount} at your earliest convenience.\n\n{invoice_list}\n\n{payment_instructions}\n\nIf you have already paid, please disregard this reminder.\n\nBest regards,"},"payment_reminders":{"email_subject":"Payment reminder from {entity_name}","email_body":"Hello,\n\nThe invoices below are overdue. Please arrange payment of {total_amount} at your earliest convenience.\n\n{invoice_list}\n\n{payment_instructions}\n\nIf you have already paid, please disregard this reminder.\n\nBest regards,","payment_instructions":"Please remit payment using the bank details shown on the document."},"tax_rules":null},"account_id":"acc_6595a27b5d35015c3ef0c3fd","metadata":{},"country_rules":{"max_taxes_per_item":3,"features":["us_tax_rate_lookup","e_invoicing"]},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created minimal entity with US country and currency"},"EU Entity":{"value":{"id":"ent_8595a27b5d35015c3ef0c3ff","name":"Orbital Systems GmbH","address":"Musterstraße 123","address_2":null,"post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","currency_code":"EUR","locale":"de-DE","tax_number":"DE123456789","tax_number_2":"12/345/67890","company_number":"HRB 12345","email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":true,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"{yyyy}-{nnnnn}","delivery_note":"{yyyy}-{nnnnn}","expense":"{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Rechnung {document_number} von {entity_name}","invoice_body":"Anbei finden Sie die Rechnung {document_number}.\nFälligkeitsdatum: {document_due_date}.","estimate_subject":"Angebot {document_number} von {entity_name}","estimate_body":"Anbei finden Sie das Angebot {document_number}.\nGültig bis: {document_valid_until}.","credit_note_subject":"Gutschrift {document_number} von {entity_name}","credit_note_body":"Anbei finden Sie die Gutschrift {document_number}.","advance_invoice_subject":"Vorausrechnung {document_number} von {entity_name}","advance_invoice_body":"Anbei finden Sie die Vorausrechnung {document_number}.","delivery_note_subject":"Lieferschein {document_number} von {entity_name}","delivery_note_body":"Anbei finden Sie den Lieferschein {document_number}."},"default_invoice_due_days":30,"default_invoice_payment_terms":null,"default_estimate_valid_days":30,"document_footer":"{entity_name}","default_document_signature":"{entity_name}","overdue_notifications":{"enabled":false,"threshold_days":[7,14,30],"email_subject":"Zahlungserinnerung von {entity_name}","email_body":"Dies ist eine Erinnerung an überfällige Rechnungen von {entity_name}.\n\n{invoice_list}\n\nBitte prüfen Sie den offenen Betrag und veranlassen Sie die Zahlung."},"payment_reminders":{"email_subject":"Zahlungserinnerung von {entity_name}","email_body":"Dies ist eine Erinnerung an überfällige Rechnungen von {entity_name}.\n\n{invoice_list}\n\nBitte prüfen Sie den offenen Betrag und veranlassen Sie die Zahlung.","payment_instructions":"Bitte verwenden Sie die auf dem Dokument angegebenen Bankdaten."},"tax_rules":{"eu":{"vies_validate_vat":true,"auto_reverse_charge":false,"auto_remove_tax_export":false,"require_gross_prices":false}},"tax_clause_defaults":{"intra_eu_b2b":"§ 13b UStG (Reverse Charge)","3w_b2b":"§ 4 Nr. 1a + § 6 UStG","3w_b2c":"§ 4 Nr. 1a + § 6 UStG"}},"account_id":"acc_6595a27b5d35015c3ef0c3fd","metadata":{"industry":"Software"},"country_rules":{"max_taxes_per_item":1,"features":["eu_tax_rules","tax_clause_defaults","tax_number_2"]},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created EU entity with default tax_rules. VIES validation is enabled by default for EU entities."},"With translations":{"value":{"id":"ent_9595a27b5d35015c3ef0c410","name":"Orbital Systems GmbH","address":null,"address_2":null,"post_code":null,"city":null,"state":null,"country":"Germany","country_code":"DE","currency_code":"EUR","locale":"de-DE","tax_number":null,"tax_number_2":null,"company_number":null,"email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":true,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"{yyyy}-{nnnnn}","delivery_note":"{yyyy}-{nnnnn}","expense":"{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Rechnung {document_number} von {entity_name}","invoice_body":"Anbei finden Sie die Rechnung {document_number}.\nFälligkeitsdatum: {document_due_date}.","estimate_subject":"Angebot {document_number} von {entity_name}","estimate_body":"Anbei finden Sie das Angebot {document_number}.\nGültig bis: {document_valid_until}.","credit_note_subject":"Gutschrift {document_number} von {entity_name}","credit_note_body":"Anbei finden Sie die Gutschrift {document_number}.","advance_invoice_subject":"Vorausrechnung {document_number} von {entity_name}","advance_invoice_body":"Anbei finden Sie die Vorausrechnung {document_number}.","delivery_note_subject":"Lieferschein {document_number} von {entity_name}","delivery_note_body":"Anbei finden Sie den Lieferschein {document_number}."},"default_invoice_due_days":30,"default_invoice_payment_terms":null,"default_estimate_valid_days":30,"document_footer":"{entity_name}","default_document_signature":"{entity_name}","overdue_notifications":{"enabled":false,"threshold_days":[7,14,30],"email_subject":"Zahlungserinnerung von {entity_name}","email_body":"Dies ist eine Erinnerung an überfällige Rechnungen von {entity_name}.\n\n{invoice_list}\n\nBitte prüfen Sie den offenen Betrag und veranlassen Sie die Zahlung."},"payment_reminders":{"email_subject":"Zahlungserinnerung von {entity_name}","email_body":"Dies ist eine Erinnerung an überfällige Rechnungen von {entity_name}.\n\n{invoice_list}\n\nBitte prüfen Sie den offenen Betrag und veranlassen Sie die Zahlung.","payment_instructions":"Bitte verwenden Sie die auf dem Dokument angegebenen Bankdaten."},"tax_rules":{"eu":{"vies_validate_vat":true,"auto_reverse_charge":false,"auto_remove_tax_export":false,"require_gross_prices":false}},"tax_clause_defaults":{"intra_eu_b2b":"§ 13b UStG (Reverse Charge)","3w_b2b":"§ 4 Nr. 1a + § 6 UStG","3w_b2c":"§ 4 Nr. 1a + § 6 UStG"},"translations":{"default_invoice_note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"document_footer":{"de-DE":"Orbital Systems GmbH"},"default_document_signature":{"de-DE":"Orbital Systems Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Anbei finden Sie die Rechnung {document_number}."}},"tax_clause_defaults":{"intra_eu_b2b":{"de-DE":"Steuerschuldnerschaft des Leistungsempfaengers."}}}},"account_id":"acc_6595a27b5d35015c3ef0c3fd","metadata":{},"country_rules":{"max_taxes_per_item":1,"features":["eu_tax_rules","tax_clause_defaults","tax_number_2"]},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created entity with translated default document and email content"},"Complete":{"value":{"id":"ent_7595a27b5d35015c3ef0c3fe","name":"Orbital Systems GmbH","address":"Musterstraße 123","address_2":"Building A","post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","currency_code":"EUR","locale":"de-DE","tax_number":"DE123456789","tax_number_2":"12/345/67890","company_number":"HRB 12345","email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":true,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"{yyyy}-{nnnnn}","delivery_note":"{yyyy}-{nnnnn}","expense":"{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Rechnung {document_number} von {entity_name}","invoice_body":"Anbei finden Sie die Rechnung {document_number}.\nFälligkeitsdatum: {document_due_date}.","estimate_subject":"Angebot {document_number} von {entity_name}","estimate_body":"Anbei finden Sie das Angebot {document_number}.\nGültig bis: {document_valid_until}.","credit_note_subject":"Gutschrift {document_number} von {entity_name}","credit_note_body":"Anbei finden Sie die Gutschrift {document_number}.","advance_invoice_subject":"Vorausrechnung {document_number} von {entity_name}","advance_invoice_body":"Anbei finden Sie die Vorausrechnung {document_number}.","delivery_note_subject":"Lieferschein {document_number} von {entity_name}","delivery_note_body":"Anbei finden Sie den Lieferschein {document_number}."},"default_invoice_due_days":30,"default_invoice_payment_terms":null,"default_estimate_valid_days":30,"document_footer":"{entity_name}","default_document_signature":"{entity_name}","overdue_notifications":{"enabled":false,"threshold_days":[7,14,30],"email_subject":"Zahlungserinnerung von {entity_name}","email_body":"Dies ist eine Erinnerung an überfällige Rechnungen von {entity_name}.\n\n{invoice_list}\n\nBitte prüfen Sie den offenen Betrag und veranlassen Sie die Zahlung."},"payment_reminders":{"email_subject":"Zahlungserinnerung von {entity_name}","email_body":"Dies ist eine Erinnerung an überfällige Rechnungen von {entity_name}.\n\n{invoice_list}\n\nBitte prüfen Sie den offenen Betrag und veranlassen Sie die Zahlung.","payment_instructions":"Bitte verwenden Sie die auf dem Dokument angegebenen Bankdaten."},"tax_rules":{"eu":{"vies_validate_vat":true,"auto_reverse_charge":false,"auto_remove_tax_export":false,"require_gross_prices":false}},"tax_clause_defaults":{"intra_eu_b2b":"§ 13b UStG (Reverse Charge)","3w_b2b":"§ 4 Nr. 1a + § 6 UStG","3w_b2c":"§ 4 Nr. 1a + § 6 UStG"},"translations":{"default_invoice_note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"document_footer":{"de-DE":"Orbital Systems GmbH"},"default_document_signature":{"de-DE":"Orbital Systems Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Anbei finden Sie die Rechnung {document_number}."}},"tax_clause_defaults":{"intra_eu_b2b":{"de-DE":"Steuerschuldnerschaft des Leistungsempfaengers."}}}},"account_id":"acc_6595a27b5d35015c3ef0c3fd","metadata":{"industry":"Technology","size":"Medium"},"country_rules":{"max_taxes_per_item":1,"features":["eu_tax_rules","tax_clause_defaults","tax_number_2","epc_qr"]},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created complete EU entity with all fields and default tax_rules"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getEntities","summary":"List all entities","description":"Retrieve a paginated list of entities with optional filtering and sorting. Supports cursor-based pagination for efficient navigation, flexible JSON querying with MongoDB-style operators, full-text search across entity names and countries, and sorting by various entity properties.","security":[{"Bearer":[]}],"tags":["Entities"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","name","country","created_at","updated_at","-id","-name","-country","-created_at","-updated_at"]},{"type":"array","items":{"type":"string","enum":["id","name","country","created_at","updated_at","-id","-name","-country","-created_at","-updated_at"]}}],"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, name, country, currency_code, created_at, updated_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, name, country, currency_code, created_at, updated_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"type":"string","description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","example":"Acme Corporation"},"required":false,"description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","name":"search","in":"query"},{"schema":{"type":"string","enum":["live","sandbox"],"default":"live","description":"Environment making queries on. Defaults to \"live\".","example":"sandbox"},"required":false,"description":"Environment making queries on. Defaults to \"live\".","name":"environment","in":"query"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"List of Entities","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Entity"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"ent_7595a27b5d35015c3ef0c3fe","name":"Orbital Systems GmbH","address":"Musterstraße 123","address_2":"Building A","post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","currency_code":"EUR","locale":"de-DE","tax_number":"DE123456789","tax_number_2":"12/345/67890","company_number":"HRB 12345","email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":true,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"{yyyy}-{nnnnn}","delivery_note":"{yyyy}-{nnnnn}","expense":"{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Rechnung {document_number} von {entity_name}","invoice_body":"Anbei finden Sie die Rechnung {document_number}.\nFälligkeitsdatum: {document_due_date}.","estimate_subject":"Angebot {document_number} von {entity_name}","estimate_body":"Anbei finden Sie das Angebot {document_number}.\nGültig bis: {document_valid_until}.","credit_note_subject":"Gutschrift {document_number} von {entity_name}","credit_note_body":"Anbei finden Sie die Gutschrift {document_number}.","advance_invoice_subject":"Vorausrechnung {document_number} von {entity_name}","advance_invoice_body":"Anbei finden Sie die Vorausrechnung {document_number}.","delivery_note_subject":"Lieferschein {document_number} von {entity_name}","delivery_note_body":"Anbei finden Sie den Lieferschein {document_number}."},"default_invoice_due_days":30,"default_invoice_payment_terms":null,"default_estimate_valid_days":30,"document_footer":"{entity_name}","default_document_signature":"{entity_name}","overdue_notifications":{"enabled":false,"threshold_days":[7,14,30],"email_subject":"Zahlungserinnerung von {entity_name}","email_body":"Dies ist eine Erinnerung an überfällige Rechnungen von {entity_name}.\n\n{invoice_list}\n\nBitte prüfen Sie den offenen Betrag und veranlassen Sie die Zahlung."},"payment_reminders":{"email_subject":"Zahlungserinnerung von {entity_name}","email_body":"Dies ist eine Erinnerung an überfällige Rechnungen von {entity_name}.\n\n{invoice_list}\n\nBitte prüfen Sie den offenen Betrag und veranlassen Sie die Zahlung.","payment_instructions":"Bitte verwenden Sie die auf dem Dokument angegebenen Bankdaten."},"tax_rules":{"eu":{"vies_validate_vat":true,"auto_reverse_charge":false,"auto_remove_tax_export":false,"require_gross_prices":false}},"tax_clause_defaults":{"intra_eu_b2b":"§ 13b UStG (Reverse Charge)","3w_b2b":"§ 4 Nr. 1a + § 6 UStG","3w_b2c":"§ 4 Nr. 1a + § 6 UStG"},"translations":{"default_invoice_note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"document_footer":{"de-DE":"Orbital Systems GmbH"},"default_document_signature":{"de-DE":"Orbital Systems Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Anbei finden Sie die Rechnung {document_number}."}},"tax_clause_defaults":{"intra_eu_b2b":{"de-DE":"Steuerschuldnerschaft des Leistungsempfaengers."}}}},"account_id":"acc_6595a27b5d35015c3ef0c3fd","metadata":{"industry":"Technology","size":"Medium"},"country_rules":{"max_taxes_per_item":1,"features":["eu_tax_rules","tax_clause_defaults","tax_number_2","epc_qr"]},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of entities"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities/{id}":{"get":{"operationId":"getEntityById","summary":"Get entity by ID","description":"Retrieve a single legal entity by its unique identifier. Returns the full entity including settings, metadata, and computed country rules.","security":[{"Bearer":[]}],"tags":["Entities"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"Entity instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"},"examples":{"200":{"value":{"id":"ent_7595a27b5d35015c3ef0c3fe","name":"Orbital Systems GmbH","address":"Musterstraße 123","address_2":"Building A","post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","currency_code":"EUR","locale":"de-DE","tax_number":"DE123456789","tax_number_2":"12/345/67890","company_number":"HRB 12345","email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":true,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"{yyyy}-{nnnnn}","delivery_note":"{yyyy}-{nnnnn}","expense":"{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Rechnung {document_number} von {entity_name}","invoice_body":"Anbei finden Sie die Rechnung {document_number}.\nFälligkeitsdatum: {document_due_date}.","estimate_subject":"Angebot {document_number} von {entity_name}","estimate_body":"Anbei finden Sie das Angebot {document_number}.\nGültig bis: {document_valid_until}.","credit_note_subject":"Gutschrift {document_number} von {entity_name}","credit_note_body":"Anbei finden Sie die Gutschrift {document_number}.","advance_invoice_subject":"Vorausrechnung {document_number} von {entity_name}","advance_invoice_body":"Anbei finden Sie die Vorausrechnung {document_number}.","delivery_note_subject":"Lieferschein {document_number} von {entity_name}","delivery_note_body":"Anbei finden Sie den Lieferschein {document_number}."},"default_invoice_due_days":30,"default_invoice_payment_terms":null,"default_estimate_valid_days":30,"document_footer":"{entity_name}","default_document_signature":"{entity_name}","overdue_notifications":{"enabled":false,"threshold_days":[7,14,30],"email_subject":"Zahlungserinnerung von {entity_name}","email_body":"Dies ist eine Erinnerung an überfällige Rechnungen von {entity_name}.\n\n{invoice_list}\n\nBitte prüfen Sie den offenen Betrag und veranlassen Sie die Zahlung."},"payment_reminders":{"email_subject":"Zahlungserinnerung von {entity_name}","email_body":"Dies ist eine Erinnerung an überfällige Rechnungen von {entity_name}.\n\n{invoice_list}\n\nBitte prüfen Sie den offenen Betrag und veranlassen Sie die Zahlung.","payment_instructions":"Bitte verwenden Sie die auf dem Dokument angegebenen Bankdaten."},"tax_rules":{"eu":{"vies_validate_vat":true,"auto_reverse_charge":false,"auto_remove_tax_export":false,"require_gross_prices":false}},"tax_clause_defaults":{"intra_eu_b2b":"§ 13b UStG (Reverse Charge)","3w_b2b":"§ 4 Nr. 1a + § 6 UStG","3w_b2c":"§ 4 Nr. 1a + § 6 UStG"},"translations":{"default_invoice_note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"document_footer":{"de-DE":"Orbital Systems GmbH"},"default_document_signature":{"de-DE":"Orbital Systems Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Anbei finden Sie die Rechnung {document_number}."}},"tax_clause_defaults":{"intra_eu_b2b":{"de-DE":"Steuerschuldnerschaft des Leistungsempfaengers."}}}},"account_id":"acc_6595a27b5d35015c3ef0c3fd","metadata":{"industry":"Technology","size":"Medium"},"country_rules":{"max_taxes_per_item":1,"features":["eu_tax_rules","tax_clause_defaults","tax_number_2","epc_qr"]},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created complete EU entity with all fields and default tax_rules"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"patchEntity","summary":"Update an entity","description":"Update an existing entity's details. All fields are optional; only provided fields will be updated. Use this to modify entity information, address, tax details, or custom settings. Settings are merged per top-level key: keys you omit keep their current value, so send only the keys you want to change. Two keys merge one level deeper: settings.translations merges per translation namespace, and settings.unit_number_sequence_starts merges per document type and business unit. Fiscalization and other dedicated-endpoint settings (settings.furs, settings.fina, settings.slovenia, settings.e_invoicing, settings.revenue_recognition) cannot be modified here and are silently ignored if sent — manage them via their dedicated endpoints (e.g. PUT /fiscalization/furs/settings, PUT /fiscalization/fina/settings). Note: Country and country_code cannot be changed after entity creation.","security":[{"Bearer":[]}],"tags":["Entities"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"requestBody":{"description":"Update Entity Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"address":{"type":["string","null"],"maxLength":500},"address_2":{"type":["string","null"],"maxLength":500},"post_code":{"type":["string","null"],"maxLength":20},"city":{"type":["string","null"],"maxLength":100},"state":{"type":["string","null"],"maxLength":100},"currency_code":{"type":["string","null"],"maxLength":3},"locale":{"type":["string","null"],"maxLength":20},"timezone":{"type":"string","maxLength":100,"description":"IANA timezone used for business calendar dates, including recurring document issue dates.","example":"Europe/Ljubljana"},"tax_number":{"type":["string","null"],"maxLength":50},"tax_number_2":{"type":["string","null"],"maxLength":50},"company_number":{"type":["string","null"],"maxLength":50},"phone":{"type":["string","null"],"maxLength":50},"email":{"type":["string","null"],"maxLength":255},"website":{"type":["string","null"],"maxLength":500},"fiscal_region_code":{"type":["string","null"],"maxLength":10},"starting_capital":{"type":["number","null"],"minimum":-140737488355328,"maximum":140737488355327},"is_tax_subject":{"type":"boolean"},"is_enabled":{"type":"boolean","description":"Whether the entity is enabled. Disabled entities cannot create documents (invoices, estimates, etc.) but all data remains accessible and settings can be updated."},"settings":{"type":"object","properties":{"pdf_template":{"type":["string","null"],"enum":["modern","classic","condensed","minimal","fashion","timeless_modern_full_data",null],"description":"Default PDF template for document rendering. Defaults to 'modern' if not set.","example":"modern"},"number_formats":{"type":["object","null"],"properties":{"invoice":{"type":["string","null"]},"estimate":{"type":["string","null"]},"credit_note":{"type":["string","null"]},"advance_invoice":{"type":["string","null"]},"delivery_note":{"type":["string","null"]},"expense":{"type":["string","null"]}}},"unit_number_formats":{"type":["object","null"],"properties":{"invoice":{"type":["string","null"]},"estimate":{"type":["string","null"]},"credit_note":{"type":["string","null"]},"advance_invoice":{"type":["string","null"]},"delivery_note":{"type":["string","null"]}}},"number_sequence_starts":{"anyOf":[{"$ref":"#/components/schemas/NumberSequenceStarts"},{"type":"null"}]},"unit_number_sequence_starts":{"anyOf":[{"$ref":"#/components/schemas/UnitNumberSequenceStarts"},{"type":"null"}]},"primary_color":{"type":["string","null"],"pattern":"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"},"logo_scale_percent":{"type":["integer","null"],"minimum":30,"maximum":100,"description":"Scale the PDF logo size as a percentage of the template default size. 100 keeps the original size.","example":70},"has_logo":{"type":["boolean","null"]},"has_signature":{"type":["boolean","null"]},"default_invoice_due_days":{"type":["integer","null"],"exclusiveMinimum":0,"description":"Default number of days until invoice is due (from invoice date)","example":30},"default_estimate_valid_days":{"type":["integer","null"],"exclusiveMinimum":0,"description":"Default number of days until estimate expires (from estimate date)","example":30},"email":{"type":["string","null"],"format":"email","description":"Sender email address used for outgoing document and reminder emails. Falls back to the platform default sender when not set. Set to null to clear.","example":"billing@example.com"},"email_defaults":{"type":["object","null"],"properties":{"invoice_subject":{"type":["string","null"],"description":"Default subject line for invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_due_date}, {document_total}, {document_currency}","example":"Invoice {document_number} from {entity_name}"},"invoice_body":{"type":["string","null"],"description":"Default body text for invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_due_date}, {document_total}, {document_currency}","example":"Please find invoice {document_number} attached.\nDue date: {document_due_date}."},"estimate_subject":{"type":["string","null"],"description":"Default subject line for estimate emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_valid_until}, {document_total}, {document_currency}","example":"Estimate {document_number} from {entity_name}"},"estimate_body":{"type":["string","null"],"description":"Default body text for estimate emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_valid_until}, {document_total}, {document_currency}","example":"Please find estimate {document_number} attached.\nValid until: {document_valid_until}."},"credit_note_subject":{"type":["string","null"],"description":"Default subject line for credit note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Credit note {document_number} from {entity_name}"},"credit_note_body":{"type":["string","null"],"description":"Default body text for credit note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Please find credit note {document_number} attached."},"advance_invoice_subject":{"type":["string","null"],"description":"Default subject line for advance invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Advance invoice {document_number} from {entity_name}"},"advance_invoice_body":{"type":["string","null"],"description":"Default body text for advance invoice emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Please find advance invoice {document_number} attached."},"delivery_note_subject":{"type":["string","null"],"description":"Default subject line for delivery note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Delivery note {document_number} from {entity_name}"},"delivery_note_body":{"type":["string","null"],"description":"Default body text for delivery note emails. Available variables: {document_number}, {entity_name}, {entity_email}, {entity_address}, {entity_post_code}, {entity_city}, {entity_country}, {entity_tax_number}, {entity_company_number}, {customer_name}, {document_date}, {document_total}, {document_currency}","example":"Please find delivery note {document_number} attached."}}},"default_invoice_note":{"type":["string","null"],"description":"Default note for new invoices. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Payment due by {document_due_date}. Please reference invoice {document_number} when making payment."},"default_invoice_payment_terms":{"type":["string","null"],"description":"Default payment terms for new invoices. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Please remit payment using the bank details shown on the document."},"default_estimate_note":{"type":["string","null"],"description":"Default note for new estimates. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_valid_until}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"This estimate is valid until {document_valid_until}."},"default_estimate_payment_terms":{"type":["string","null"],"description":"Default payment terms for new estimates. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_valid_until}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Payment due upon acceptance."},"default_credit_note_note":{"type":["string","null"],"description":"Default note for new credit notes. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Credit note for invoice {document_number}."},"default_credit_note_payment_terms":{"type":["string","null"],"description":"Default payment terms for new credit notes. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Credit will be applied to your account."},"default_advance_invoice_note":{"type":["string","null"],"description":"Default note for new advance invoices. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Advance payment requested for {document_number}."},"default_delivery_note_note":{"type":["string","null"],"description":"Default note for new delivery notes. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"Goods delivered under delivery note {document_number}."},"document_footer":{"type":["string","null"],"maxLength":500,"description":"Footer text for PDF documents. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"{entity_name} | Due Date: {document_due_date} | Invoice #{document_number}"},"default_document_signature":{"type":["string","null"],"description":"Default signature text for all new documents. Supports template variables: {entity_name}, {entity_email}, {document_number}, {document_date}, {document_due_date}, {document_total}, {document_currency}, {customer_name}, {customer_email}, {current_date}, {current_year}","example":"{entity_name}"},"translations":{"anyOf":[{"$ref":"#/components/schemas/EntitySettingsTranslations"},{"type":"null"}],"description":"Translated default document-facing settings keyed by full supported locales. Used when new documents inherit default texts and when document defaults are rendered in an explicit non-default language."},"calculation":{"anyOf":[{"$ref":"#/components/schemas/CalculationSettings"},{"type":"null"}],"description":"Document calculation defaults. Controls whether newly calculated documents use the standard B2B net-first model or the B2C gross-discount model by default."},"slovenia":{"anyOf":[{"$ref":"#/components/schemas/SloveniaEntitySettings"},{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}],"description":"Slovenia-specific tax profile used by yearly eDavki exports and future Slovenia-specific reporting flows. Ignored by the generic entity update endpoint; use the dedicated settings endpoint."},"furs":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean","default":false,"description":"Whether FURS fiscalization is enabled for this entity","example":true},"default_skip_fiscalization":{"type":"boolean","default":false,"description":"Whether new FURS-capable documents should start with fiscalization skipped by default. Payment type rules still override this and require fiscalization for non-bank-transfer payments.","example":false},"numbering_strategy":{"type":"string","enum":["B","C"],"description":"Numbering strategy: B (device-level) or C (centralized). Optional - can be set per-premise.","example":"C"},"operator_tax_number":{"type":"string","description":"Operator tax number for this entity (used when creating invoices via API key)","example":"12345678"},"operator_label":{"type":"string","description":"Operator label/name for this entity","example":"Cash Register 1"},"foreign_operator":{"type":"boolean","description":"Whether the operator is a foreign legal entity","example":false},"environment":{"type":"string","enum":["test","production"],"description":"FURS environment override (test or production). When omitted, derived from entity environment.","example":"test"}}},{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}],"description":"FURS (Slovenia) fiscalization settings. Ignored by the generic entity update endpoint; use the dedicated FURS settings endpoint."},"fina":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean","default":false,"description":"Whether CIS (FINA) fiscalization is enabled for this entity","example":true},"operator_oib":{"type":"string","minLength":11,"maxLength":11,"description":"OIB of the operator (11 digits). Used when creating invoices via API key.","example":"12345678901"},"operator_label":{"type":"string","description":"Operator label/name for this entity","example":"Cash Register 1"},"u_sust_pdv":{"type":"boolean","default":true,"description":"Whether the entity is in the PDV (VAT) system. Most businesses are.","example":true},"numbering_sequence":{"type":"string","enum":["N","P"],"default":"P","description":"Numbering sequence: P (per premise) or N (per device)","example":"P"},"unified_numbering":{"type":["boolean","null"],"description":"When enabled (default: true), all documents use the same FINA numbering sequence regardless of transaction type (domestic/non-domestic)","example":true},"certificate_expiry":{"type":"string","description":"Certificate expiry date (ISO 8601 format)","example":"2026-12-31T23:59:59.000Z"}}},{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}],"description":"FINA (Croatia) CIS fiscalization settings. Ignored by the generic entity update endpoint; use the dedicated FINA settings endpoint."},"pt":{"anyOf":[{"$ref":"#/components/schemas/PtEntitySettings"},{"type":"null"}],"description":"Portugal operator defaults used for PT document creation when request-level or user-level PT operator data is not available."},"tax_rules":{"anyOf":[{"$ref":"#/components/schemas/TaxRules"},{"type":"null"}],"description":"Tax rules engine settings. Controls automatic tax behaviors based on entity location and transaction characteristics (VIES validation, reverse charge, export tax removal). Defaults are set automatically based on entity country. Set to null for non-EU entities."},"overdue_notifications":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Enable automatic overdue invoice notification emails to customers","example":true},"threshold_days":{"type":"array","items":{"type":"integer","exclusiveMinimum":0},"default":[7,14,30],"description":"Days overdue when notification emails are sent (exact day match). Email is triggered when any invoice hits these thresholds.","example":[7,14,30]},"email_subject":{"type":["string","null"],"deprecated":true,"description":"Deprecated legacy content field. Use settings.payment_reminders.email_subject for reminder email content. Automatic reminder scheduling remains configured under overdue_notifications.","example":"Payment reminder from {entity_name}"},"email_body":{"type":["string","null"],"deprecated":true,"description":"Deprecated legacy content field. Use settings.payment_reminders.email_body for reminder email content. Automatic reminder scheduling remains configured under overdue_notifications.","example":"Hello,\n\nThe invoices below are overdue. Please arrange payment of {total_amount} at your earliest convenience.\n\n{invoice_list}\n\n{payment_instructions}\n\nIf you have already paid, please disregard this reminder.\n\nBest regards,"}},"description":"Settings for automatic overdue invoice notification emails to customers"},"payment_reminders":{"type":["object","null"],"properties":{"email_subject":{"type":["string","null"],"description":"Default subject for manual and automatic payment reminder emails. Available variables: {customer_name}, {entity_name}, {overdue_count}","example":"Payment reminder from {entity_name}"},"email_body":{"type":["string","null"],"description":"Default body for manual and automatic payment reminder emails. Available variables: {customer_name}, {entity_name}, {invoice_list}, {payment_instructions}, {total_amount}, {entity_email}, {overdue_count}. Missing invoice list or payment instructions blocks are appended automatically.","example":"Hello,\n\nThe invoices below are overdue. Please arrange payment of {total_amount} at your earliest convenience.\n\n{invoice_list}\n\n{payment_instructions}\n\nIf you have already paid, please disregard this reminder.\n\nBest regards,"},"payment_instructions":{"type":["string","null"],"description":"Default payment instructions for payment reminder emails. Supports bank placeholders: {iban}, {bic}, {bank_name}, {account_number}, {routing_number}, {sort_code}","example":"Please remit payment to IBAN {iban}."}},"description":"Shared content defaults for manual and automatic payment reminder emails. Automatic reminder scheduling remains configured under overdue_notifications."},"upn_qr":{"anyOf":[{"$ref":"#/components/schemas/UpnQrSettings"},{"type":"null"}],"description":"UPN QR payment slip settings (Slovenia only). Displays payment QR code on invoices for easy bank transfers."},"epc_qr":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","description":"Whether EPC QR code is enabled on EUR invoices (SEPA countries)","example":true}},"required":["enabled"],"description":"EPC QR code settings (SEPA countries). Displays SEPA credit transfer QR code on EUR invoices for easy bank payment."},"hub3_qr":{"anyOf":[{"$ref":"#/components/schemas/Hub3QrSettings"},{"type":"null"}],"description":"Croatian HUB3 PDF417 payment barcode settings. Displays the barcode used by Croatian banking apps on EUR invoices."},"bank_accounts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/EntityBankAccount"},"description":"Bank accounts for receiving payments. The first account with is_default=true (or first in list) is used for new invoices."},"eslog_validation_enabled":{"type":["boolean","null"],"description":"Enable e-SLOG 2.0 validation for documents. Only applicable for Slovenian entities (country_code = 'SI'). When enabled, documents are validated against e-SLOG 2.0 requirements and can be exported as e-SLOG XML if valid.","example":true},"ujp_validation_with_eslog_enabled":{"type":["boolean","null"],"description":"When true for Slovenian entities, API/UI document create flows that enable e-SLOG also validate UJP package/envelope requirements for supported document types. Web may expose UJP download as a secondary e-SLOG dropdown action when current UJP validation is valid.","example":false},"xrechnung":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Enable German XRechnung XML validation by default and export actions for finalized German invoices and credit notes. Only applies to German entities whose country rules include e_invoicing. Final create/update calls only fail on validation errors when the request xrechnung.validation_required flag is true; XRechnung export always requires a current valid validation result.","example":true}},"description":"German XRechnung XML export settings. Separate from Peppol sending/onboarding settings and separate from document xrechnung validation state."},"zugferd":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Enable German ZUGFeRD/Factur-X validation by default and export actions for finalized German invoices and credit notes. Only applies to German entities whose country rules include e_invoicing. Final create/update calls only fail on validation errors when the request zugferd.validation_required flag is true; ZUGFeRD export always requires a current valid validation result.","example":true}},"description":"German ZUGFeRD/Factur-X PDF export settings. Separate from Peppol sending/onboarding settings and separate from document zugferd validation state."},"delivery_note_hide_prices":{"type":["boolean","null"],"description":"Default hide_prices setting for new delivery notes. When true, prices and totals are hidden (packing list mode).","example":false},"credit_note_negative_values":{"type":["boolean","null"],"description":"When true (default), credit note PDFs display line item quantities and totals as negative values while keeping prices positive. Zero quantities and totals stay unsigned. Set to false to show quantities and totals as positive.","example":true},"show_payment_amounts":{"type":["boolean","null"],"description":"When true, rendered document payment/refund sections show the payment amount next to each payment type. Defaults to false, which shows only the payment or refund type.","example":false},"receipt_note":{"type":["string","null"],"maxLength":500,"description":"Default note printed on thermal receipts."},"receipt_footer":{"type":["string","null"],"maxLength":500,"description":"Default footer text printed on thermal receipts (e.g. IBAN, thank-you message)."},"receipt_signature":{"type":["string","null"],"maxLength":200,"description":"Default signature / issuer label printed on thermal receipts."},"tax_clause_defaults":{"anyOf":[{"$ref":"#/components/schemas/TaxClauseDefaults"},{"type":"null"}],"description":"Default tax clauses per transaction type. Auto-applied to documents based on transaction type determination. Supports template variables: {entity_name}, {customer_name}, {document_number}, etc."},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/EInvoicingEntitySettings"},{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}],"description":"E-invoicing settings. Ignored by the generic entity update endpoint; use the dedicated e-invoicing settings endpoint."},"revenue_recognition":{"anyOf":[{"$ref":"#/components/schemas/RevenueRecognitionSettings"},{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}],"description":"Deferred revenue and accrued revenue settings. Ignored by the generic entity update endpoint; use the dedicated revenue recognition settings endpoint."},"expense_recognition":{"anyOf":[{"$ref":"#/components/schemas/ExpenseRecognitionSettings"},{"type":"object","properties":{},"additionalProperties":{}},{"type":"null"}],"description":"Expense recognition settings. Ignored by the generic entity update endpoint; use the dedicated expense recognition settings endpoint."}}},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"additionalProperties":false},"examples":{"Update name":{"value":{"name":"Starward Equipment Co."},"description":"Update entity name"},"Update address":{"value":{"address":"Dunajska cesta 100","city":"Ljubljana","post_code":"1000"},"description":"Update entity address details"},"Update document locale":{"value":{"locale":"de-DE"},"description":"Change the default document-facing locale. PDF, email, and shareable document output use this unless an action-level locale or language override is provided."},"Update email defaults":{"value":{"settings":{"email_defaults":{"invoice_subject":"Invoice {document_number} from {entity_name}","invoice_body":"Please find invoice {document_number} attached.\n\n[View document]({invoice_link})"}}},"description":"Customize default email templates while keeping document variables available."}}}}},"responses":{"200":{"description":"Updated Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"},"examples":{"Update name":{"value":{"id":"ent_6595a27b5d35015c3ef0c3fd","name":"Starward Equipment Co.","address":null,"address_2":null,"post_code":null,"city":null,"state":null,"country":"Slovenia","country_code":"SI","currency_code":"EUR","locale":"en-US","tax_number":null,"tax_number_2":null,"company_number":null,"email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":true,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"{yyyy}-{nnnnn}","delivery_note":"{yyyy}-{nnnnn}","expense":"{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Invoice {document_number} from {entity_name}","invoice_body":"Please find invoice {document_number} attached.\nDue date: {document_due_date}.\n\n[View document]({invoice_link})","estimate_subject":"{document_label} {document_number} from {entity_name}","estimate_body":"Please find {document_label} {document_number} attached.\nValid until: {document_valid_until}.\n\n[View document]({invoice_link})","credit_note_subject":"Credit note {document_number} from {entity_name}","credit_note_body":"Please find credit note {document_number} attached.\n\n[View document]({invoice_link})","advance_invoice_subject":"Advance invoice {document_number} from {entity_name}","advance_invoice_body":"Please find advance invoice {document_number} attached.\n\n[View document]({invoice_link})","delivery_note_subject":"Delivery note {document_number} from {entity_name}","delivery_note_body":"Please find delivery note {document_number} attached.\n\n[View document]({invoice_link})"},"default_invoice_due_days":30,"default_invoice_payment_terms":null,"default_estimate_valid_days":30,"document_footer":"{entity_name}","default_document_signature":"{entity_name}","overdue_notifications":{"enabled":false,"threshold_days":[7,14,30],"email_subject":"Payment reminder from {entity_name}","email_body":"Hello,\n\nThe invoices below are overdue. Please arrange payment of {total_amount} at your earliest convenience.\n\n{invoice_list}\n\n{payment_instructions}\n\nIf you have already paid, please disregard this reminder.\n\nBest regards,"},"payment_reminders":{"email_subject":"Payment reminder from {entity_name}","email_body":"Hello,\n\nThe invoices below are overdue. Please arrange payment of {total_amount} at your earliest convenience.\n\n{invoice_list}\n\n{payment_instructions}\n\nIf you have already paid, please disregard this reminder.\n\nBest regards,","payment_instructions":"Please remit payment using the bank details shown on the document."},"tax_rules":{"eu":{"vies_validate_vat":true,"auto_reverse_charge":false,"auto_remove_tax_export":false,"require_gross_prices":false}},"tax_clause_defaults":{"intra_eu_b2b":"46. člen ZDDV-1","3w_b2b":"52. člen ZDDV-1","3w_b2c":"52. člen ZDDV-1"},"slovenia":{"tax_residency":"resident","accounting_exports":{"preferred_format":"vod_xml","konto_mappings":{"receivables":"1200","payables":"2200","sales_vat_22":"26000","sales_vat_95":"26001","sales_vat_5":"26002","purchase_vat_recoverable_22":"16000","purchase_vat_recoverable_95":"16001","purchase_vat_recoverable_5":"16002","sales_revenue_22":"7600","sales_revenue_95":"7601","sales_revenue_5":"7602","sales_revenue_exempt":"7680","sales_revenue_eu_goods":"7600","sales_revenue_eu_services":"7601","sales_revenue_reverse_charge":"7600","sales_revenue_third_country_goods":"7600","sales_revenue_third_country_services":"7680","purchase_expense_22":"4000","purchase_expense_95":"4001","purchase_expense_5":"4002","purchase_expense_exempt":"4680","purchase_expense_eu_goods":"4000","purchase_expense_eu_services":"4680","purchase_expense_reverse_charge":"4000","purchase_expense_third_country_goods":"4000","purchase_expense_third_country_services":"4680"}}}},"account_id":"acc_6595a27b5d35015c3ef0c3fd","metadata":{},"country_rules":{"max_taxes_per_item":1,"features":["eu_tax_rules","tax_clause_defaults","epc_qr","furs","eslog","upn_qr","kir_report","si_yearly_tax_report"]},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Updated EU entity with new name (retains country and tax_rules from creation)"},"Update address":{"value":{"id":"ent_6595a27b5d35015c3ef0c3fd","name":"Vzorec Storitve d.o.o.","address":"Dunajska cesta 100","address_2":null,"post_code":"1000","city":"Ljubljana","state":null,"country":"Slovenia","country_code":"SI","currency_code":"EUR","locale":"en-US","tax_number":"SI12345678","tax_number_2":null,"company_number":null,"email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":true,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"{yyyy}-{nnnnn}","delivery_note":"{yyyy}-{nnnnn}","expense":"{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Invoice {document_number} from {entity_name}","invoice_body":"Please find invoice {document_number} attached.\nDue date: {document_due_date}.","estimate_subject":"{document_label} {document_number} from {entity_name}","estimate_body":"Please find {document_label} {document_number} attached.\nValid until: {document_valid_until}.","credit_note_subject":"Credit note {document_number} from {entity_name}","credit_note_body":"Please find credit note {document_number} attached.","advance_invoice_subject":"Advance invoice {document_number} from {entity_name}","advance_invoice_body":"Please find advance invoice {document_number} attached.","delivery_note_subject":"Delivery note {document_number} from {entity_name}","delivery_note_body":"Please find delivery note {document_number} attached."},"default_invoice_due_days":30,"default_invoice_payment_terms":null,"default_estimate_valid_days":30,"document_footer":"{entity_name}, {entity_address}, {entity_post_code} {entity_city}","default_document_signature":"{entity_name}","overdue_notifications":{"enabled":false,"threshold_days":[7,14,30],"email_subject":"Payment reminder from {entity_name}","email_body":"Hello,\n\nThe invoices below are overdue. Please arrange payment of {total_amount} at your earliest convenience.\n\n{invoice_list}\n\n{payment_instructions}\n\nIf you have already paid, please disregard this reminder.\n\nBest regards,"},"payment_reminders":{"email_subject":"Payment reminder from {entity_name}","email_body":"Hello,\n\nThe invoices below are overdue. Please arrange payment of {total_amount} at your earliest convenience.\n\n{invoice_list}\n\n{payment_instructions}\n\nIf you have already paid, please disregard this reminder.\n\nBest regards,","payment_instructions":"Please remit payment using the bank details shown on the document."},"tax_rules":{"eu":{"vies_validate_vat":true,"auto_reverse_charge":false,"auto_remove_tax_export":false,"require_gross_prices":false}},"tax_clause_defaults":{"intra_eu_b2b":"46. člen ZDDV-1","3w_b2b":"52. člen ZDDV-1","3w_b2c":"52. člen ZDDV-1"}},"account_id":"acc_6595a27b5d35015c3ef0c3fd","metadata":{},"country_rules":{"max_taxes_per_item":1,"features":["eu_tax_rules","tax_clause_defaults","epc_qr","furs","eslog","upn_qr","kir_report"]},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Updated EU entity with new address"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities/{id}/enable":{"post":{"operationId":"enableEntity","summary":"Enable an entity","description":"Re-enable a disabled entity. Enabled entities can create documents (invoices, estimates, credit notes, etc.). This operation is idempotent - enabling an already enabled entity has no effect.","security":[{"Bearer":[]}],"tags":["Entities"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"Enabled Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"},"example":{"id":"ent_7595a27b5d35015c3ef0c3fe","name":"Orbital Systems GmbH","address":"Musterstraße 123","address_2":"Building A","post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","currency_code":"EUR","locale":"de-DE","tax_number":"DE123456789","tax_number_2":"12/345/67890","company_number":"HRB 12345","email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":true,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"{yyyy}-{nnnnn}","delivery_note":"{yyyy}-{nnnnn}","expense":"{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Rechnung {document_number} von {entity_name}","invoice_body":"Anbei finden Sie die Rechnung {document_number}.\nFälligkeitsdatum: {document_due_date}.","estimate_subject":"Angebot {document_number} von {entity_name}","estimate_body":"Anbei finden Sie das Angebot {document_number}.\nGültig bis: {document_valid_until}.","credit_note_subject":"Gutschrift {document_number} von {entity_name}","credit_note_body":"Anbei finden Sie die Gutschrift {document_number}.","advance_invoice_subject":"Vorausrechnung {document_number} von {entity_name}","advance_invoice_body":"Anbei finden Sie die Vorausrechnung {document_number}.","delivery_note_subject":"Lieferschein {document_number} von {entity_name}","delivery_note_body":"Anbei finden Sie den Lieferschein {document_number}."},"default_invoice_due_days":30,"default_invoice_payment_terms":null,"default_estimate_valid_days":30,"document_footer":"{entity_name}","default_document_signature":"{entity_name}","overdue_notifications":{"enabled":false,"threshold_days":[7,14,30],"email_subject":"Zahlungserinnerung von {entity_name}","email_body":"Dies ist eine Erinnerung an überfällige Rechnungen von {entity_name}.\n\n{invoice_list}\n\nBitte prüfen Sie den offenen Betrag und veranlassen Sie die Zahlung."},"payment_reminders":{"email_subject":"Zahlungserinnerung von {entity_name}","email_body":"Dies ist eine Erinnerung an überfällige Rechnungen von {entity_name}.\n\n{invoice_list}\n\nBitte prüfen Sie den offenen Betrag und veranlassen Sie die Zahlung.","payment_instructions":"Bitte verwenden Sie die auf dem Dokument angegebenen Bankdaten."},"tax_rules":{"eu":{"vies_validate_vat":true,"auto_reverse_charge":false,"auto_remove_tax_export":false,"require_gross_prices":false}},"tax_clause_defaults":{"intra_eu_b2b":"§ 13b UStG (Reverse Charge)","3w_b2b":"§ 4 Nr. 1a + § 6 UStG","3w_b2c":"§ 4 Nr. 1a + § 6 UStG"},"translations":{"default_invoice_note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"document_footer":{"de-DE":"Orbital Systems GmbH"},"default_document_signature":{"de-DE":"Orbital Systems Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Anbei finden Sie die Rechnung {document_number}."}},"tax_clause_defaults":{"intra_eu_b2b":{"de-DE":"Steuerschuldnerschaft des Leistungsempfaengers."}}}},"account_id":"acc_6595a27b5d35015c3ef0c3fd","metadata":{"industry":"Technology","size":"Medium"},"country_rules":{"max_taxes_per_item":1,"features":["eu_tax_rules","tax_clause_defaults","tax_number_2","epc_qr"]},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities/{id}/disable":{"post":{"operationId":"disableEntity","summary":"Disable an entity","description":"Disable an entity. Disabled entities cannot create documents (invoices, estimates, credit notes, etc.) but all data remains accessible and settings can still be updated. This operation is idempotent - disabling an already disabled entity has no effect.","security":[{"Bearer":[]}],"tags":["Entities"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"Disabled Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"},"example":{"id":"ent_7595a27b5d35015c3ef0c3fe","name":"Orbital Systems GmbH","address":"Musterstraße 123","address_2":"Building A","post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","currency_code":"EUR","locale":"de-DE","tax_number":"DE123456789","tax_number_2":"12/345/67890","company_number":"HRB 12345","email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":false,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"{yyyy}-{nnnnn}","delivery_note":"{yyyy}-{nnnnn}","expense":"{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Rechnung {document_number} von {entity_name}","invoice_body":"Anbei finden Sie die Rechnung {document_number}.\nFälligkeitsdatum: {document_due_date}.","estimate_subject":"Angebot {document_number} von {entity_name}","estimate_body":"Anbei finden Sie das Angebot {document_number}.\nGültig bis: {document_valid_until}.","credit_note_subject":"Gutschrift {document_number} von {entity_name}","credit_note_body":"Anbei finden Sie die Gutschrift {document_number}.","advance_invoice_subject":"Vorausrechnung {document_number} von {entity_name}","advance_invoice_body":"Anbei finden Sie die Vorausrechnung {document_number}.","delivery_note_subject":"Lieferschein {document_number} von {entity_name}","delivery_note_body":"Anbei finden Sie den Lieferschein {document_number}."},"default_invoice_due_days":30,"default_invoice_payment_terms":null,"default_estimate_valid_days":30,"document_footer":"{entity_name}","default_document_signature":"{entity_name}","overdue_notifications":{"enabled":false,"threshold_days":[7,14,30],"email_subject":"Zahlungserinnerung von {entity_name}","email_body":"Dies ist eine Erinnerung an überfällige Rechnungen von {entity_name}.\n\n{invoice_list}\n\nBitte prüfen Sie den offenen Betrag und veranlassen Sie die Zahlung."},"payment_reminders":{"email_subject":"Zahlungserinnerung von {entity_name}","email_body":"Dies ist eine Erinnerung an überfällige Rechnungen von {entity_name}.\n\n{invoice_list}\n\nBitte prüfen Sie den offenen Betrag und veranlassen Sie die Zahlung.","payment_instructions":"Bitte verwenden Sie die auf dem Dokument angegebenen Bankdaten."},"tax_rules":{"eu":{"vies_validate_vat":true,"auto_reverse_charge":false,"auto_remove_tax_export":false,"require_gross_prices":false}},"tax_clause_defaults":{"intra_eu_b2b":"§ 13b UStG (Reverse Charge)","3w_b2b":"§ 4 Nr. 1a + § 6 UStG","3w_b2c":"§ 4 Nr. 1a + § 6 UStG"},"translations":{"default_invoice_note":{"de-DE":"Vielen Dank fuer Ihren Auftrag."},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 30 Tagen."},"document_footer":{"de-DE":"Orbital Systems GmbH"},"default_document_signature":{"de-DE":"Orbital Systems Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Anbei finden Sie die Rechnung {document_number}."}},"tax_clause_defaults":{"intra_eu_b2b":{"de-DE":"Steuerschuldnerschaft des Leistungsempfaengers."}}}},"account_id":"acc_6595a27b5d35015c3ef0c3fd","metadata":{"industry":"Technology","size":"Medium"},"country_rules":{"max_taxes_per_item":1,"features":["eu_tax_rules","tax_clause_defaults","tax_number_2","epc_qr"]},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities/{id}/email-sender":{"get":{"operationId":"getEntityEmailSender","summary":"Get entity sender email configuration","description":"Returns the entity-level custom sender, inherited white-label sender, and effective sender source. Only verified custom senders affect delivery.","security":[{"Bearer":[]}],"tags":["Entities"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"Entity sender email configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityEmailSenderResponse"},"example":{"configured":{"email":"billing@example.com","verification_status":"pending","verified_at":null,"domain":"example.com","email_verification_status":"pending","domain_verification_status":"pending","domain_dkim_tokens":["dkim-token"],"last_checked_at":"2026-08-05T12:00:00.000Z"},"inherited":null,"effective":{"source":"default","email":"noreply@spaceinvoices.com","verified":true}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"putEntityEmailSender","summary":"Set entity sender email","description":"Sets or clears the entity-level custom From email for a production entity. Saving reserves the normalized address to the account and starts SES email/domain verification. Use null to clear the entity override; clearing does not release the account's SES identity ownership.","security":[{"Bearer":[]}],"tags":["Entities"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"requestBody":{"description":"Email Sender Update Request Body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSenderUpdateRequest"},"example":{"email":"billing@example.com"}}}},"responses":{"200":{"description":"Updated entity sender email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityEmailSenderResponse"},"example":{"configured":{"email":"billing@example.com","verification_status":"pending","verified_at":null,"domain":"example.com","email_verification_status":"pending","domain_verification_status":"pending","domain_dkim_tokens":["dkim-token"],"last_checked_at":"2026-08-05T12:00:00.000Z"},"inherited":null,"effective":{"source":"default","email":"noreply@spaceinvoices.com","verified":true}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Sender email is owned by another account"},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"SES verification is temporarily unavailable"}}},"delete":{"operationId":"deleteEntityEmailSender","summary":"Clear entity sender email","description":"Clears the entity-level custom sender override. The entity may still inherit a verified white-label sender. Account ownership of the SES identity is intentionally retained.","security":[{"Bearer":[]}],"tags":["Entities"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"Updated entity sender email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityEmailSenderResponse"},"example":{"configured":null,"inherited":null,"effective":{"source":"default","email":"noreply@spaceinvoices.com","verified":true}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entities/{id}/email-sender/recheck":{"post":{"operationId":"recheckEntityEmailSender","summary":"Recheck entity sender email verification","description":"Refresh SES verification status for the entity-level custom sender email and domain. This does not resend verification; saving a sender starts verification.","security":[{"Bearer":[]}],"tags":["Entities"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"Refreshed entity sender email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityEmailSenderResponse"},"example":{"configured":{"email":"billing@example.com","verification_status":"pending","verified_at":null,"domain":"example.com","email_verification_status":"pending","domain_verification_status":"pending","domain_dkim_tokens":["dkim-token"],"last_checked_at":"2026-08-05T12:00:00.000Z"},"inherited":null,"effective":{"source":"default","email":"noreply@spaceinvoices.com","verified":true}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"SES verification status is temporarily unavailable"}}}},"/documents/export":{"get":{"operationId":"exportDocuments","summary":"Export documents to Excel or CSV","description":"Export filtered documents to Excel (XLSX) or CSV format.\nSupports date range filtering (maximum 1 year) and the same query filters as list endpoints.\nReturns a downloadable file with all base document fields including flattened customer/issuer data and tax breakdowns.","security":[{"Bearer":[]}],"tags":["Exports"],"parameters":[{"schema":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice","delivery_note"],"description":"Document type to export","example":"invoice"},"required":false,"description":"Document type to export","name":"type","in":"query"},{"schema":{"type":"string","description":"Comma-separated document types for a multi-sheet XLSX export. Only supported when format is xlsx.","example":"invoice,credit_note"},"required":false,"description":"Comma-separated document types for a multi-sheet XLSX export. Only supported when format is xlsx.","name":"types","in":"query"},{"schema":{"type":"string","enum":["xlsx","csv"],"description":"Export format","example":"xlsx"},"required":true,"description":"Export format","name":"format","in":"query"},{"schema":{"type":"string","description":"Start date filter (ISO 8601 date). Date range cannot exceed 1 year.","example":"2024-01-01"},"required":false,"description":"Start date filter (ISO 8601 date). Date range cannot exceed 1 year.","name":"date_from","in":"query"},{"schema":{"type":"string","description":"End date filter (ISO 8601 date). Date range cannot exceed 1 year.","example":"2024-12-31"},"required":false,"description":"End date filter (ISO 8601 date). Date range cannot exceed 1 year.","name":"date_to","in":"query"},{"schema":{"type":["string","null"],"enum":["en","de","sl","it","fr","es","pt","nl","pl","hr","sv","fi","et","bg","cs","sk","nb","is",null],"description":"Language for column headers. Defaults to the entity locale when omitted.","example":"en"},"required":false,"description":"Language for column headers. Defaults to the entity locale when omitted.","name":"language","in":"query"},{"schema":{"type":"string","description":"JSON query filter (same as list endpoints)"},"required":false,"description":"JSON query filter (same as list endpoints)","name":"query","in":"query"},{"schema":{"type":"string","description":"Full-text search"},"required":false,"description":"Full-text search","name":"search","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Exported file (Excel or CSV based on format parameter)","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/export/sales-per-item":{"get":{"operationId":"exportSalesPerItem","summary":"Export sales per item for a period","description":"Export aggregated sales data per item (product/service) for a given date range.\nIncludes quantities sold/returned, average price, and totals.\nAggregates across invoices, credit notes, and advance invoices.\nItems are grouped by catalog item ID when available, or by exact name match.","security":[{"Bearer":[]}],"tags":["Exports"],"parameters":[{"schema":{"type":"string","enum":["xlsx","csv"],"description":"Export format","example":"xlsx"},"required":true,"description":"Export format","name":"format","in":"query"},{"schema":{"type":"string","description":"Start date filter (ISO 8601 date). Required. Date range cannot exceed 1 year.","example":"2024-01-01"},"required":true,"description":"Start date filter (ISO 8601 date). Required. Date range cannot exceed 1 year.","name":"date_from","in":"query"},{"schema":{"type":"string","description":"End date filter (ISO 8601 date). Required. Date range cannot exceed 1 year.","example":"2024-12-31"},"required":true,"description":"End date filter (ISO 8601 date). Required. Date range cannot exceed 1 year.","name":"date_to","in":"query"},{"schema":{"type":["string","null"],"enum":["en","de","sl","it","fr","es","pt","nl","pl","hr","sv","fi","et","bg","cs","sk","nb","is",null],"description":"Language for column headers. Defaults to the entity locale when omitted.","example":"en"},"required":false,"description":"Language for column headers. Defaults to the entity locale when omitted.","name":"language","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Exported file (Excel or CSV based on format parameter)","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/export/revenue-by-category":{"get":{"operationId":"exportRevenueByCategory","summary":"Export accrued revenue by category for a period","description":"Export accrued revenue grouped by financial category for a given date range.\nIncludes invoices, standalone advance invoices, and credit notes.\nCredit notes are subtracted and uncategorized lines are grouped into an 'Uncategorized' bucket.","security":[{"Bearer":[]}],"tags":["Exports"],"parameters":[{"schema":{"type":"string","enum":["xlsx","csv"],"description":"Export format","example":"xlsx"},"required":true,"description":"Export format","name":"format","in":"query"},{"schema":{"type":"string","description":"Start date filter (ISO 8601 date). Required. Date range cannot exceed 1 year.","example":"2024-01-01"},"required":true,"description":"Start date filter (ISO 8601 date). Required. Date range cannot exceed 1 year.","name":"date_from","in":"query"},{"schema":{"type":"string","description":"End date filter (ISO 8601 date). Required. Date range cannot exceed 1 year.","example":"2024-12-31"},"required":true,"description":"End date filter (ISO 8601 date). Required. Date range cannot exceed 1 year.","name":"date_to","in":"query"},{"schema":{"type":["string","null"],"enum":["en","de","sl","it","fr","es","pt","nl","pl","hr","sv","fi","et","bg","cs","sk","nb","is",null],"description":"Language for column headers. Defaults to the entity locale when omitted.","example":"en"},"required":false,"description":"Language for column headers. Defaults to the entity locale when omitted.","name":"language","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Exported file (Excel or CSV based on format parameter)","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/export/pdf":{"post":{"operationId":"startPdfExport","summary":"Start bulk PDF export","description":"Start a background job to export documents as a ZIP archive of PDFs.\nSupports date range filtering (maximum 1 year) or specific document IDs.\nWhen using a user access token, you will receive an email with a download link when the export is ready.\nWhen using an API key, poll the job status endpoint for progress.","security":[{"Bearer":[]}],"tags":["Exports"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PdfExportByDocumentIds"},{"$ref":"#/components/schemas/PdfExportByDateRange"}]},"examples":{"invoiceExport":{"value":{"types":["invoice"],"date_from":"2024-01-01","date_to":"2024-12-31"},"summary":"Export all invoices for 2024"},"multiTypeExport":{"value":{"types":["invoice","credit_note"],"date_from":"2024-06-01","date_to":"2024-06-30"},"summary":"Export invoices and credit notes for June 2024"},"selectedDocuments":{"value":{"document_ids":["inv_clx1234567890","est_clx0987654321"]},"summary":"Export specific documents by ID (types inferred from prefixes)"},"dateRangeWithEmailNotification":{"value":{"types":["invoice","estimate","credit_note"],"date_from":"2024-01-01","date_to":"2024-03-31"},"summary":"Export a quarter of documents; user tokens receive an email when the ZIP is ready"}}}}},"responses":{"202":{"description":"Export job started","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Export job ID","example":"clx1234567890"},"status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"Export job status","example":"pending"},"message":{"type":"string","description":"Status message","example":"Export started. You will receive an email when ready."}},"required":["id","status","message"]},"examples":{"success":{"value":{"id":"clx1234567890abcdef","status":"pending","message":"Export started. You will receive an email when ready."},"summary":"Export job created successfully"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/export/pdf/{jobId}":{"get":{"operationId":"getPdfExportStatus","summary":"Get PDF export job status","description":"Check the status and progress of a bulk PDF export job.","security":[{"Bearer":[]}],"tags":["Exports"],"parameters":[{"schema":{"type":"string","description":"Export job ID","example":"expjob_clx1234567890"},"required":true,"description":"Export job ID","name":"jobId","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Export job status","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Export job ID","example":"expjob_clx1234567890"},"status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"Export job status","example":"pending"},"progress":{"type":"number","description":"Export progress. While processing, this is the number of processed documents so far. Completed jobs return 100.","example":12},"total_docs":{"type":["number","null"],"description":"Total number of documents to export","example":25},"file_url":{"type":["string","null"],"description":"Download URL for the completed export","example":"https://storage.example.com/exports/export.zip"},"file_name":{"type":["string","null"],"description":"Suggested ZIP filename for the completed export","example":"acme-invoices_invoices_2024-01-01_2024-12-31.zip"},"error":{"type":["string","null"],"description":"Error message if the export failed","example":null},"result":{"type":["object","null"],"properties":{"exported_docs":{"type":"number","description":"Number of files included in the archive","example":12},"skipped_docs":{"type":"number","description":"Number of documents skipped because they were not valid for export","example":3}},"required":["exported_docs","skipped_docs"],"description":"Optional async export result summary"}},"required":["id","status","progress","total_docs","file_url","file_name","error","result"]},"examples":{"inProgress":{"value":{"id":"expjob_clx1234567890","status":"processing","progress":50,"total_docs":25,"file_url":null,"file_name":"starward_documents_2024-06-01_2024-06-30.zip","error":null,"result":null},"summary":"Export job in progress"},"completedWithSkippedDocuments":{"value":{"id":"expjob_clx1234567890","status":"completed","progress":100,"total_docs":25,"file_url":"https://storage.example.com/exports/starward_eslog_2024.zip","file_name":"starward_eslog_2024.zip","error":null,"result":{"exported_docs":22,"skipped_docs":3}},"summary":"Completed e-SLOG export with skipped invalid documents"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/export/pdf/{jobId}/download":{"get":{"operationId":"downloadPdfExport","summary":"Download completed PDF export archive","description":"Download a completed PDF export ZIP archive through the authenticated API.","security":[{"Bearer":[]}],"tags":["Exports"],"parameters":[{"schema":{"type":"string","description":"Export job ID","example":"expjob_clx1234567890"},"required":true,"description":"Export job ID","name":"jobId","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"ZIP archive","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/export/eslog":{"post":{"operationId":"startEslogExport","summary":"Start bulk e-SLOG export","description":"Start a background job to export valid e-SLOG XML documents as a ZIP archive.\nSupports date range filtering (maximum 1 year) or specific document IDs.\nOnly available for Slovenian entities with e-SLOG support.\nDocuments without valid e-SLOG validation are skipped.","security":[{"Bearer":[]}],"tags":["Exports"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/EslogExportByDocumentIds"},{"$ref":"#/components/schemas/EslogExportByDateRange"}]},"examples":{"validSlovenianInvoices":{"value":{"types":["invoice"],"date_from":"2024-01-01","date_to":"2024-12-31"},"summary":"Export valid Slovenian e-SLOG invoices for a period"},"selectedValidatedDocuments":{"value":{"document_ids":["inv_clx1234567890","cre_clx0987654321"]},"summary":"Export selected documents that already have valid e-SLOG validation"}}}}},"responses":{"202":{"description":"e-SLOG export job started","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Export job ID","example":"clx1234567890"},"status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"Export job status","example":"pending"},"message":{"type":"string","description":"Status message","example":"Export started. You will receive an email when ready."}},"required":["id","status","message"]},"examples":{"startedWithSkippedDocuments":{"value":{"id":"clx1234567890abcdef","status":"pending","message":"e-SLOG export started. Invalid or not-yet-validated documents are skipped and reported in the completed job status."},"summary":"e-SLOG export job created; invalid documents are skipped"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Entity is not eligible for bulk e-SLOG export","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/export/eslog/{jobId}":{"get":{"operationId":"getEslogExportStatus","summary":"Get e-SLOG export job status","description":"Check the status and progress of a bulk e-SLOG export job.","security":[{"Bearer":[]}],"tags":["Exports"],"parameters":[{"schema":{"type":"string","description":"Export job ID","example":"expjob_clx1234567890"},"required":true,"description":"Export job ID","name":"jobId","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"e-SLOG export job status","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Export job ID","example":"expjob_clx1234567890"},"status":{"type":"string","enum":["pending","processing","completed","failed"],"description":"Export job status","example":"pending"},"progress":{"type":"number","description":"Export progress. While processing, this is the number of processed documents so far. Completed jobs return 100.","example":12},"total_docs":{"type":["number","null"],"description":"Total number of documents to export","example":25},"file_url":{"type":["string","null"],"description":"Download URL for the completed export","example":"https://storage.example.com/exports/export.zip"},"file_name":{"type":["string","null"],"description":"Suggested ZIP filename for the completed export","example":"acme-invoices_invoices_2024-01-01_2024-12-31.zip"},"error":{"type":["string","null"],"description":"Error message if the export failed","example":null},"result":{"type":["object","null"],"properties":{"exported_docs":{"type":"number","description":"Number of files included in the archive","example":12},"skipped_docs":{"type":"number","description":"Number of documents skipped because they were not valid for export","example":3}},"required":["exported_docs","skipped_docs"],"description":"Optional async export result summary"}},"required":["id","status","progress","total_docs","file_url","file_name","error","result"]},"examples":{"inProgress":{"value":{"id":"expjob_clx1234567890","status":"processing","progress":50,"total_docs":25,"file_url":null,"file_name":"starward_documents_2024-06-01_2024-06-30.zip","error":null,"result":null},"summary":"Export job in progress"},"completedWithSkippedDocuments":{"value":{"id":"expjob_clx1234567890","status":"completed","progress":100,"total_docs":25,"file_url":"https://storage.example.com/exports/starward_eslog_2024.zip","file_name":"starward_eslog_2024.zip","error":null,"result":{"exported_docs":22,"skipped_docs":3}},"summary":"Completed e-SLOG export with skipped invalid documents"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/export/eslog/{jobId}/download":{"get":{"operationId":"downloadEslogExport","summary":"Download completed e-SLOG export archive","description":"Download a completed e-SLOG export ZIP archive through the authenticated API.","security":[{"Bearer":[]}],"tags":["Exports"],"parameters":[{"schema":{"type":"string","description":"Export job ID","example":"expjob_clx1234567890"},"required":true,"description":"Export job ID","name":"jobId","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"ZIP archive","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/financial-categories":{"get":{"operationId":"getFinancialCategories","summary":"List financial categories","security":[{"Bearer":[]}],"tags":["Financial Categories"],"parameters":[{"schema":{"type":"boolean"},"required":false,"name":"include_archived","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of financial categories","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FinancialCategoryResponse"}}},"required":["data"]},"examples":{"Default":{"value":{"data":[{"id":"fcat_abc123","entity_id":"ent_abc123","name":"Mission services","color":"#93c5fd","sort_order":0,"archived_at":null,"created_at":"2026-04-15T10:00:00.000Z","updated_at":"2026-04-15T10:00:00.000Z"}]},"description":"List of active financial categories for the entity."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createFinancialCategory","summary":"Create a financial category","security":[{"Bearer":[]}],"tags":["Financial Categories"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Create financial category","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"color":{"type":["string","null"],"minLength":1,"maxLength":32},"sort_order":{"type":["integer","null"],"minimum":0}},"required":["name"],"additionalProperties":false},"examples":{"Minimal":{"value":{"name":"Mission services","color":"#93c5fd","sort_order":0},"description":"Create a reusable financial category for reporting."},"Hosting revenue":{"value":{"name":"Ground station revenue","color":"#2563eb","sort_order":10},"description":"Create a category that can be assigned to recurring/subscription line items."},"Implementation revenue":{"value":{"name":"Implementation revenue","color":"#16a34a","sort_order":20},"description":"Create a category for one-off services so reports can separate setup and recurring revenue."}}}}},"responses":{"201":{"description":"Created financial category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialCategoryResponse"},"examples":{"Minimal":{"value":{"id":"fcat_abc123","entity_id":"ent_abc123","name":"Mission services","color":"#93c5fd","sort_order":0,"archived_at":null,"created_at":"2026-04-15T10:00:00.000Z","updated_at":"2026-04-15T10:00:00.000Z"},"description":"Created financial category."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/financial-categories/{id}":{"patch":{"operationId":"updateFinancialCategory","summary":"Update a financial category","security":[{"Bearer":[]}],"tags":["Financial Categories"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update financial category","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"],"minLength":1,"maxLength":200},"color":{"type":["string","null"],"minLength":1,"maxLength":32},"sort_order":{"type":["integer","null"],"minimum":0}},"additionalProperties":false},"examples":{"Minimal":{"value":{"name":"Mission services retainer","color":"#60a5fa"},"description":"Rename a category and adjust its color."}}}}},"responses":{"200":{"description":"Updated financial category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialCategoryResponse"},"examples":{"Minimal":{"value":{"id":"fcat_abc123","entity_id":"ent_abc123","name":"Mission services retainer","color":"#60a5fa","sort_order":0,"archived_at":null,"created_at":"2026-04-15T10:00:00.000Z","updated_at":"2026-04-15T12:00:00.000Z"},"description":"Updated financial category."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteFinancialCategory","summary":"Archive a financial category","security":[{"Bearer":[]}],"tags":["Financial Categories"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Financial category archived successfully"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/financial-categories/revenue-summary":{"get":{"operationId":"getRevenueByFinancialCategory","summary":"Get accrued revenue grouped by financial category","security":[{"Bearer":[]}],"tags":["Financial Categories"],"parameters":[{"schema":{"type":"string","description":"Start date filter (ISO 8601 date).","example":"2026-01-01"},"required":true,"description":"Start date filter (ISO 8601 date).","name":"date_from","in":"query"},{"schema":{"type":"string","description":"End date filter (ISO 8601 date).","example":"2026-12-31"},"required":true,"description":"End date filter (ISO 8601 date).","name":"date_to","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Revenue by category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevenueByCategoryResponse"},"examples":{"Default":{"value":{"data":[{"financial_category_id":"fcat_abc123","name":"Mission services","color":"#93c5fd","amount":12000,"percentage":75,"currency_code":"EUR"},{"financial_category_id":null,"name":"Uncategorized","color":null,"amount":4000,"percentage":25,"currency_code":"EUR"}],"total":16000,"currency_code":"EUR","date_from":"2026-01-01","date_to":"2026-12-31"},"description":"Accrued revenue grouped by effective financial category."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/financial-categories/document-items/batch":{"patch":{"operationId":"updateDocumentItemFinancialCategories","summary":"Atomically update saved categories for multiple document line items","security":[{"Bearer":[]}],"tags":["Financial Categories"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update multiple document item financial categories","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assignments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Document line item ID to update.","example":"item_abc123"},"financial_category_id":{"type":["string","null"],"description":"Category to assign to this saved document line. Use null to mark the line as uncategorized.","example":"fcat_abc123"}},"required":["id","financial_category_id"],"additionalProperties":false},"minItems":1,"description":"Atomic batch of saved document line category updates."}},"required":["assignments"],"additionalProperties":false},"examples":{"Minimal":{"value":{"assignments":[{"id":"item_abc123","financial_category_id":"fcat_abc123"},{"id":"item_def456","financial_category_id":null}]},"description":"Atomically apply multiple document line category assignments."},"Assign by line":{"value":{"assignments":[{"id":"item_setup","financial_category_id":"fcat_implementation"},{"id":"item_hosting","financial_category_id":"fcat_hosting"}]},"description":"Assign categories to multiple saved document lines in one request."}}}}},"responses":{"200":{"description":"Updated document item financial category assignments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentItemFinancialCategoryAssignments"},"examples":{"Minimal":{"value":[{"document_item_id":"item_abc123","financial_category_id":"fcat_abc123"},{"document_item_id":"item_def456","financial_category_id":null}],"description":"Updated saved document line item assignments."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/financial-categories/document-items/{id}":{"patch":{"operationId":"updateDocumentItemFinancialCategory","summary":"Update the saved category for a document line item","security":[{"Bearer":[]}],"tags":["Financial Categories"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update document item financial category","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"financial_category_id":{"type":["string","null"],"description":"Category to assign to this saved document line. Use null to explicitly mark the line as uncategorized.","example":"fcat_abc123"}},"required":["financial_category_id"],"additionalProperties":false},"examples":{"Minimal":{"value":{"financial_category_id":"fcat_abc123"},"description":"Assign a category to a saved document line item."},"Clear assignment":{"value":{"financial_category_id":null},"description":"Explicitly clear a document line category so it reports as Uncategorized."}}}}},"responses":{"200":{"description":"Updated document item financial category assignment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentItemFinancialCategoryAssignment"},"examples":{"Minimal":{"value":{"document_item_id":"item_abc123","financial_category_id":"fcat_abc123"},"description":"Updated saved document line item assignment."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/business-units":{"get":{"operationId":"getBusinessUnits","summary":"List business units","security":[{"Bearer":[]}],"tags":["Business Units"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"type":["boolean","null"],"description":"Include archived business units in the response."},"required":false,"description":"Include archived business units in the response.","name":"include_archived","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of business units","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BusinessUnitResponse"}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"next_cursor":{"type":["string","null"]},"prev_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}},"required":["total","next_cursor","prev_cursor","has_more"]}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"unit_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","name":"Starward Berlin Office","address":null,"address_2":null,"post_code":null,"city":null,"state":null,"country":null,"country_code":null,"email":null,"phone":null,"website":null,"settings":{},"numbering_index":1,"logo_file_id":null,"signature_file_id":null,"is_active":true,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z","deleted_at":null},{"id":"unit_7595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","name":"Starward Berlin Office","address":"Friedrichstraße 95","address_2":"Floor 2","post_code":"10117","city":"Berlin","state":"Berlin","country":"Germany","country_code":"DE","email":"berlin@starward.example","phone":"+49 30 12345678","website":"https://berlin.starward.example","settings":{"pdf_template":"modern","primary_color":"#1D4ED8","logo_scale_percent":110,"default_invoice_note":"Issued by {entity_name} / {unit_name}","default_invoice_payment_terms":"Payment due in 15 days.","document_footer":"Questions? Contact {entity_email}.","default_document_signature":"Starward Berlin Office team","bank_accounts":[{"type":"iban","iban":"DE89370400440532013000","bic":"COBADEFFXXX","bank_name":"Commerzbank AG","name":"Starward Berlin Office Account","is_default":true}],"delivery_note_hide_prices":false,"credit_note_negative_values":true,"show_payment_amounts":true,"email_defaults":{"invoice_subject":"Invoice {document_number} from {entity_name}","invoice_body":"Hello {customer_name},\n\nPlease find your invoice attached."},"translations":{"default_invoice_note":{"de-DE":"Ausgestellt von {entity_name} / {unit_name}"},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 15 Tagen."},"document_footer":{"de-DE":"Fragen? Kontaktieren Sie {entity_email}."},"default_document_signature":{"de-DE":"Starward Berlin Office Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Hallo {customer_name},\n\nanbei finden Sie Ihre Rechnung."}}}},"numbering_index":2,"logo_file_id":"file_6595a27b5d35015c3ef0c3ff","signature_file_id":"file_8595a27b5d35015c3ef0c400","is_active":true,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null}],"pagination":{"total":2,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of business units"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createBusinessUnit","summary":"Create a business unit","security":[{"Bearer":[]}],"tags":["Business Units"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Create Business Unit Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"address":{"type":["string","null"],"maxLength":500},"address_2":{"type":["string","null"],"maxLength":500},"post_code":{"type":["string","null"],"maxLength":20},"city":{"type":["string","null"],"maxLength":100},"state":{"type":["string","null"],"maxLength":100},"country":{"type":["string","null"],"maxLength":100},"country_code":{"type":["string","null"],"maxLength":2},"email":{"type":["string","null"],"maxLength":255},"phone":{"type":["string","null"],"maxLength":50},"website":{"type":["string","null"],"maxLength":500},"settings":{"allOf":[{"$ref":"#/components/schemas/BusinessUnitSettings"},{"type":["object","null"]}]},"logo_file_id":{"type":["string","null"],"maxLength":36},"signature_file_id":{"type":["string","null"],"maxLength":36}},"required":["name"],"additionalProperties":false},"examples":{"Minimal":{"value":{"name":"Starward Berlin Office"},"description":"Minimal business unit with only the required name."},"With translations":{"value":{"name":"Starward Berlin Office","settings":{"translations":{"default_invoice_note":{"de-DE":"Ausgestellt von {entity_name} / {unit_name}"},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 15 Tagen."},"document_footer":{"de-DE":"Fragen? Kontaktieren Sie {entity_email}."},"default_document_signature":{"de-DE":"Starward Berlin Office Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Hallo {customer_name},\n\nanbei finden Sie Ihre Rechnung."}}}}},"description":"Business unit with translated default content overrides."},"Complete":{"value":{"name":"Starward Berlin Office","address":"Friedrichstraße 95","address_2":"Floor 2","post_code":"10117","city":"Berlin","state":"Berlin","country":"Germany","country_code":"DE","email":"berlin@starward.example","phone":"+49 30 12345678","website":"https://berlin.starward.example","settings":{"pdf_template":"modern","primary_color":"#1D4ED8","logo_scale_percent":110,"default_invoice_note":"Issued by {entity_name} / {unit_name}","default_invoice_payment_terms":"Payment due in 15 days.","document_footer":"Questions? Contact {entity_email}.","default_document_signature":"Starward Berlin Office team","bank_accounts":[{"type":"iban","iban":"DE89370400440532013000","bic":"COBADEFFXXX","bank_name":"Commerzbank AG","name":"Starward Berlin Office Account","is_default":true}],"delivery_note_hide_prices":false,"credit_note_negative_values":true,"show_payment_amounts":true,"email_defaults":{"invoice_subject":"Invoice {document_number} from {entity_name}","invoice_body":"Hello {customer_name},\n\nPlease find your invoice attached."},"translations":{"default_invoice_note":{"de-DE":"Ausgestellt von {entity_name} / {unit_name}"},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 15 Tagen."},"document_footer":{"de-DE":"Fragen? Kontaktieren Sie {entity_email}."},"default_document_signature":{"de-DE":"Starward Berlin Office Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Hallo {customer_name},\n\nanbei finden Sie Ihre Rechnung."}}}}},"description":"Business unit with branding, defaults, and bank-account overrides."}}}}},"responses":{"201":{"description":"Created business unit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessUnitResponse"},"examples":{"Minimal":{"value":{"id":"unit_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","name":"Starward Berlin Office","address":null,"address_2":null,"post_code":null,"city":null,"state":null,"country":null,"country_code":null,"email":null,"phone":null,"website":null,"settings":{},"numbering_index":1,"logo_file_id":null,"signature_file_id":null,"is_active":true,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z","deleted_at":null},"description":"Created minimal business unit."},"With translations":{"value":{"id":"unit_8595a27b5d35015c3ef0c401","entity_id":"ent_6595a27b5d35015c3ef0c3fd","name":"Starward Berlin Office","address":null,"address_2":null,"post_code":null,"city":null,"state":null,"country":null,"country_code":null,"email":null,"phone":null,"website":null,"settings":{"translations":{"default_invoice_note":{"de-DE":"Ausgestellt von {entity_name} / {unit_name}"},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 15 Tagen."},"document_footer":{"de-DE":"Fragen? Kontaktieren Sie {entity_email}."},"default_document_signature":{"de-DE":"Starward Berlin Office Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Hallo {customer_name},\n\nanbei finden Sie Ihre Rechnung."}}}},"numbering_index":2,"logo_file_id":null,"signature_file_id":null,"is_active":true,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Created business unit with translated default content overrides."},"Complete":{"value":{"id":"unit_7595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","name":"Starward Berlin Office","address":"Friedrichstraße 95","address_2":"Floor 2","post_code":"10117","city":"Berlin","state":"Berlin","country":"Germany","country_code":"DE","email":"berlin@starward.example","phone":"+49 30 12345678","website":"https://berlin.starward.example","settings":{"pdf_template":"modern","primary_color":"#1D4ED8","logo_scale_percent":110,"default_invoice_note":"Issued by {entity_name} / {unit_name}","default_invoice_payment_terms":"Payment due in 15 days.","document_footer":"Questions? Contact {entity_email}.","default_document_signature":"Starward Berlin Office team","bank_accounts":[{"type":"iban","iban":"DE89370400440532013000","bic":"COBADEFFXXX","bank_name":"Commerzbank AG","name":"Starward Berlin Office Account","is_default":true}],"delivery_note_hide_prices":false,"credit_note_negative_values":true,"show_payment_amounts":true,"email_defaults":{"invoice_subject":"Invoice {document_number} from {entity_name}","invoice_body":"Hello {customer_name},\n\nPlease find your invoice attached."},"translations":{"default_invoice_note":{"de-DE":"Ausgestellt von {entity_name} / {unit_name}"},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 15 Tagen."},"document_footer":{"de-DE":"Fragen? Kontaktieren Sie {entity_email}."},"default_document_signature":{"de-DE":"Starward Berlin Office Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Hallo {customer_name},\n\nanbei finden Sie Ihre Rechnung."}}}},"numbering_index":2,"logo_file_id":"file_6595a27b5d35015c3ef0c3ff","signature_file_id":"file_8595a27b5d35015c3ef0c400","is_active":true,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Created business unit with full settings."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/business-units/{id}":{"get":{"operationId":"getBusinessUnitById","summary":"Get a business unit","security":[{"Bearer":[]}],"tags":["Business Units"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":["boolean","null"]},"required":false,"name":"include_archived","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Business unit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessUnitResponse"},"examples":{"200":{"value":{"id":"unit_7595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","name":"Starward Berlin Office","address":"Friedrichstraße 95","address_2":"Floor 2","post_code":"10117","city":"Berlin","state":"Berlin","country":"Germany","country_code":"DE","email":"berlin@starward.example","phone":"+49 30 12345678","website":"https://berlin.starward.example","settings":{"pdf_template":"modern","primary_color":"#1D4ED8","logo_scale_percent":110,"default_invoice_note":"Issued by {entity_name} / {unit_name}","default_invoice_payment_terms":"Payment due in 15 days.","document_footer":"Questions? Contact {entity_email}.","default_document_signature":"Starward Berlin Office team","bank_accounts":[{"type":"iban","iban":"DE89370400440532013000","bic":"COBADEFFXXX","bank_name":"Commerzbank AG","name":"Starward Berlin Office Account","is_default":true}],"delivery_note_hide_prices":false,"credit_note_negative_values":true,"show_payment_amounts":true,"email_defaults":{"invoice_subject":"Invoice {document_number} from {entity_name}","invoice_body":"Hello {customer_name},\n\nPlease find your invoice attached."},"translations":{"default_invoice_note":{"de-DE":"Ausgestellt von {entity_name} / {unit_name}"},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 15 Tagen."},"document_footer":{"de-DE":"Fragen? Kontaktieren Sie {entity_email}."},"default_document_signature":{"de-DE":"Starward Berlin Office Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Hallo {customer_name},\n\nanbei finden Sie Ihre Rechnung."}}}},"numbering_index":2,"logo_file_id":"file_6595a27b5d35015c3ef0c3ff","signature_file_id":"file_8595a27b5d35015c3ef0c400","is_active":true,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Created business unit with full settings."}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateBusinessUnit","summary":"Update a business unit","security":[{"Bearer":[]}],"tags":["Business Units"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Business Unit Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"address":{"type":["string","null"],"maxLength":500},"address_2":{"type":["string","null"],"maxLength":500},"post_code":{"type":["string","null"],"maxLength":20},"city":{"type":["string","null"],"maxLength":100},"state":{"type":["string","null"],"maxLength":100},"country":{"type":["string","null"],"maxLength":100},"country_code":{"type":["string","null"],"maxLength":2},"email":{"type":["string","null"],"maxLength":255},"phone":{"type":["string","null"],"maxLength":50},"website":{"type":["string","null"],"maxLength":500},"settings":{"allOf":[{"$ref":"#/components/schemas/BusinessUnitSettings"},{"type":["object","null"]}]},"logo_file_id":{"type":["string","null"],"maxLength":36},"signature_file_id":{"type":["string","null"],"maxLength":36}},"additionalProperties":false},"examples":{"Rename":{"value":{"name":"Starward Berlin HQ"},"description":"Rename the business unit."},"Update settings":{"value":{"settings":{"pdf_template":"minimal","primary_color":"#0F172A","default_invoice_note":"Issued by {entity_name} / {unit_name}"}},"description":"Update selected business-unit document settings."}}}}},"responses":{"200":{"description":"Updated business unit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessUnitResponse"},"examples":{"Updated":{"value":{"id":"unit_7595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","name":"Starward Berlin HQ","address":"Friedrichstraße 95","address_2":"Floor 2","post_code":"10117","city":"Berlin","state":"Berlin","country":"Germany","country_code":"DE","email":"berlin@starward.example","phone":"+49 30 12345678","website":"https://berlin.starward.example","settings":{"pdf_template":"minimal","primary_color":"#0F172A","logo_scale_percent":110,"default_invoice_note":"Issued by {entity_name} / {unit_name}","default_invoice_payment_terms":"Payment due in 15 days.","document_footer":"Questions? Contact {entity_email}.","default_document_signature":"Starward Berlin Office team","bank_accounts":[{"type":"iban","iban":"DE89370400440532013000","bic":"COBADEFFXXX","bank_name":"Commerzbank AG","name":"Starward Berlin Office Account","is_default":true}],"delivery_note_hide_prices":false,"credit_note_negative_values":true,"show_payment_amounts":true,"email_defaults":{"invoice_subject":"Invoice {document_number} from {entity_name}","invoice_body":"Hello {customer_name},\n\nPlease find your invoice attached."},"translations":{"default_invoice_note":{"de-DE":"Ausgestellt von {entity_name} / {unit_name}"},"default_invoice_payment_terms":{"de-DE":"Zahlbar innerhalb von 15 Tagen."},"document_footer":{"de-DE":"Fragen? Kontaktieren Sie {entity_email}."},"default_document_signature":{"de-DE":"Starward Berlin Office Team"},"email_defaults":{"invoice_subject":{"de-DE":"Rechnung {document_number} von {entity_name}"},"invoice_body":{"de-DE":"Hallo {customer_name},\n\nanbei finden Sie Ihre Rechnung."}}}},"numbering_index":2,"logo_file_id":"file_6595a27b5d35015c3ef0c3ff","signature_file_id":"file_8595a27b5d35015c3ef0c400","is_active":true,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Updated business unit."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteBusinessUnit","summary":"Archive a business unit","security":[{"Bearer":[]}],"tags":["Business Units"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Business unit archived successfully"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/items":{"post":{"operationId":"createItem","summary":"Create a new item","description":"Create a new product or service item for use in invoices. Items can include pricing, tax information (inline or by reference), and unit details. All fields except name are optional.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Items"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Create Item Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":["string","null"],"maxLength":2000},"classification":{"type":["string","null"],"enum":["product","service","advance",null],"description":"Item classification used for Portugal SAF-T item/service typing.","example":"product"},"price":{"type":"number","description":"Net price per unit before tax in the item's currency major unit; for EUR, `29.90` means €29.90, not 2,990 cents. Provide either price OR gross_price, not both.","example":100},"gross_price":{"type":"number","description":"Gross price per unit including tax in the item's currency major unit; for EUR, `29.90` means €29.90, not 2,990 cents. If provided, net price is calculated. Provide either price OR gross_price, not both.","example":122},"unit":{"type":["string","null"],"description":"Default display unit for document lines created from this saved item.","example":"hours"},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemEInvoicingData"},{"type":"null"}],"description":"Default line-level e-invoicing options for document lines created from this saved item."},"tax_ids":{"type":"array","items":{"type":"string","maxLength":36}},"financial_category_id":{"type":["string","null"],"description":"Default financial category for this item. In v1 only income categories can be assigned.","example":"fcat_abc123"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentItemTranslations"},{"description":"Translated user-authored line-item content keyed by full supported locales. Base item fields remain the default-language source of truth."}]},{"type":"null"}],"description":"Optional or null translated user-authored line-item content keyed by full supported locales. Empty string intentionally blanks the field for that locale.","example":{"name":{"de-DE":"Beratungsleistungen"},"description":{"de-DE":"Retainer fuer Maerz"}}},"taxes":{"type":["array","null"],"items":{"type":"object","properties":{"rate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate percentage. Either rate or classification must be provided."},"classification":{"type":"string","maxLength":50,"description":"Tax classification to lookup existing tax. Either rate or classification must be provided."}}},"maxItems":2,"description":"Taxes for the item. Provide rate to auto-create, or classification to lookup existing tax."}},"required":["name"],"additionalProperties":false},"examples":{"Minimal":{"value":{"name":"Satellite Communication Module","price":1500},"description":"Minimal item with net price (before tax)"},"With Tax ID":{"value":{"name":"EVA Toolkit - Standard","price":2200,"tax_ids":["tax_6595a27b5d35015c3ef0c3fd"]},"description":"Item with reference to existing tax by ID"},"With new tax":{"value":{"name":"Ground Station Antenna Array","price":12500,"taxes":[{"rate":22}]},"description":"Item with inline tax definition (creates new tax)"},"With tax classification":{"value":{"name":"Telemetry Support Package","price":100,"taxes":[{"classification":"standard"}]},"description":"Item using an entity tax classification instead of a hard-coded rate. The classification must match an existing entity tax."},"With Gross Price":{"value":{"name":"Thermal Shielding Panel","gross_price":1037,"taxes":[{"rate":22}]},"description":"Item with gross price (includes tax). Net price is back-calculated: 1037 / 1.22 = 850"},"With translations":{"value":{"name":"Mission Planning Services","description":"Monthly mission planning retainer","price":1000,"translations":{"name":{"de-DE":"Missionsplanungsleistungen"},"description":{"de-DE":"Monatlicher Missionsplanungs-Retainer"}}},"description":"Minimal item with translated catalog-item content"},"With financial category":{"value":{"name":"Ground Segment Implementation","price":2500,"financial_category_id":"fcat_services"},"description":"Item with a default financial category. Document lines can override this with their own financial_category_id."},"Complete":{"value":{"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","price":5000,"translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"taxes":[{"rate":22}],"metadata":{"category":"software","unit":"license"}},"description":"Item with all optional fields"}}}}},"responses":{"201":{"description":"Created Item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemResponse"},"examples":{"Minimal":{"value":{"id":"item_6595a27b5d35015c3ef0c3fd","name":"Satellite Communication Module","description":null,"translations":{},"price":1500,"gross_price":null,"unit":null,"e_invoicing":null,"price_with_tax":1500,"total_tax":0,"tax_ids":[],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created minimal item without taxes"},"With Tax":{"value":{"id":"item_6595a27b5d35015c3ef0c3fd","name":"EVA Toolkit - Standard","description":null,"translations":{},"price":2200,"gross_price":null,"unit":null,"e_invoicing":null,"price_with_tax":2684,"total_tax":484,"tax_ids":["tax_6595a27b5d35015c3ef0c3fd"],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created item with referenced tax (total_tax calculated)"},"With new tax":{"value":{"id":"item_6595a27b5d35015c3ef0c3fd","name":"Ground Station Antenna Array","description":null,"translations":{},"price":12500,"gross_price":null,"unit":null,"e_invoicing":null,"price_with_tax":15250,"total_tax":2750,"tax_ids":["tax_6595a27b5d35015c3ef0c3fd"],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created item with inline tax (tax created and referenced)"},"With Gross Price":{"value":{"id":"item_6595a27b5d35015c3ef0c3fd","name":"Thermal Shielding Panel","description":null,"translations":{},"price":850,"gross_price":1037,"unit":null,"e_invoicing":null,"price_with_tax":1037,"total_tax":187,"tax_ids":["tax_6595a27b5d35015c3ef0c3fd"],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created item with gross price - net price back-calculated from gross"},"With translations":{"value":{"id":"item_8595a27b5d35015c3ef0c3ff","name":"Mission Planning Services","description":"Monthly mission planning retainer","translations":{"name":{"de-DE":"Missionsplanungsleistungen"},"description":{"de-DE":"Monatlicher Missionsplanungs-Retainer"}},"price":1000,"gross_price":null,"unit":null,"e_invoicing":null,"price_with_tax":1000,"total_tax":0,"tax_ids":[],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created item with translated catalog-item content"},"Complete":{"value":{"id":"item_7595a27b5d35015c3ef0c3fe","name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"price":5000,"gross_price":null,"unit":null,"e_invoicing":null,"price_with_tax":6100,"total_tax":1100,"tax_ids":["tax_6595a27b5d35015c3ef0c3fd"],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{"category":"software","unit":"license"},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created item with all optional fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getItems","summary":"List all items","description":"Retrieve a paginated list of items (products and services) with optional filtering and sorting. Supports cursor-based pagination, flexible JSON querying with MongoDB-style operators, full-text search, and sorting.","security":[{"Bearer":[]}],"tags":["Items"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","name","price","created_at","updated_at","-id","-name","-price","-created_at","-updated_at"]},{"type":"array","items":{"type":"string","enum":["id","name","price","created_at","updated_at","-id","-name","-price","-created_at","-updated_at"]}}],"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, name, description, price, unit, created_at, updated_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, name, description, price, unit, created_at, updated_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"type":"string","description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","example":"Acme Corporation"},"required":false,"description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","name":"search","in":"query"},{"schema":{"type":"boolean","description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items."},"required":false,"description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.","name":"deleted","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of Items","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ItemResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"item_7595a27b5d35015c3ef0c3fe","name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"price":5000,"gross_price":null,"unit":null,"e_invoicing":null,"price_with_tax":6100,"total_tax":1100,"tax_ids":["tax_6595a27b5d35015c3ef0c3fd"],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{"category":"software","unit":"license"},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of items"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/items/{id}":{"patch":{"operationId":"updateItem","summary":"Update an item","description":"Update an existing product or service item. Only the provided fields are updated. Pricing and taxes are recalculated consistently with item creation rules.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Items"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Item Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":["string","null"],"maxLength":2000},"classification":{"type":["string","null"],"enum":["product","service","advance",null],"description":"Item classification used for Portugal SAF-T item/service typing.","example":"product"},"price":{"type":"number","description":"Net price per unit before tax in the item's currency major unit; for EUR, `29.90` means €29.90, not 2,990 cents. Provide either price OR gross_price, not both.","example":100},"gross_price":{"type":"number","description":"Gross price per unit including tax in the item's currency major unit; for EUR, `29.90` means €29.90, not 2,990 cents. If provided, net price is calculated. Provide either price OR gross_price, not both.","example":122},"unit":{"type":["string","null"],"description":"Default display unit for document lines created from this saved item.","example":"hours"},"e_invoicing":{"anyOf":[{"$ref":"#/components/schemas/DocumentItemEInvoicingData"},{"type":"null"}],"description":"Default line-level e-invoicing options for document lines created from this saved item."},"tax_ids":{"type":"array","items":{"type":"string","maxLength":36}},"financial_category_id":{"type":["string","null"],"description":"Default financial category for this item. In v1 only income categories can be assigned.","example":"fcat_abc123"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"translations":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/DocumentItemTranslations"},{"description":"Translated user-authored line-item content keyed by full supported locales. Base item fields remain the default-language source of truth."}]},{"type":"null"}],"description":"Translated catalog-item content. Set to null to clear all translations.","example":{"name":{"de-DE":"Beratungsleistungen"},"description":{"de-DE":"Retainer fuer Maerz"}}},"taxes":{"type":["array","null"],"items":{"type":"object","properties":{"rate":{"type":"number","minimum":0,"maximum":100,"description":"Tax rate percentage. Either rate or classification must be provided."},"classification":{"type":"string","maxLength":50,"description":"Tax classification to lookup existing tax. Either rate or classification must be provided."}}},"maxItems":2,"description":"Taxes for the item. Provide rate to auto-create, or classification to lookup existing tax."}},"additionalProperties":false},"examples":{"Minimal":{"value":{"name":"Satellite Communication Module v2"},"description":"Rename an existing item"},"Switch to gross price":{"value":{"name":"Thermal Shielding Panel","gross_price":1098,"taxes":[{"rate":22}]},"description":"Update an item to use gross price mode and recalculate net price"}}}}},"responses":{"200":{"description":"Updated Item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemResponse"},"examples":{"Minimal":{"value":{"id":"item_6595a27b5d35015c3ef0c3fd","name":"Satellite Communication Module v2","description":null,"translations":{},"price":1500,"gross_price":null,"unit":null,"e_invoicing":null,"price_with_tax":1500,"total_tax":0,"tax_ids":[],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-02T00:00:00.000Z"},"description":"Updated item with a new name"},"Switch to gross price":{"value":{"id":"item_6595a27b5d35015c3ef0c3fd","name":"Thermal Shielding Panel","description":null,"translations":{},"price":900,"gross_price":1098,"unit":null,"e_invoicing":null,"price_with_tax":1098,"total_tax":198,"tax_ids":["tax_6595a27b5d35015c3ef0c3fd"],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-02T00:00:00.000Z"},"description":"Updated item with gross price mode and recalculated tax totals"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteItem","summary":"Delete an item","description":"Soft delete an item. The item will be moved to the trash and can be restored later.","security":[{"Bearer":[]}],"tags":["Items"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Item deleted successfully"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/items/{id}/restore":{"post":{"operationId":"restoreItem","summary":"Restore a deleted item","description":"Restore a soft-deleted item from the trash.","security":[{"Bearer":[]}],"tags":["Items"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Restored Item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemResponse"},"examples":{"Minimal":{"value":{"id":"item_6595a27b5d35015c3ef0c3fd","name":"Satellite Communication Module","description":null,"translations":{},"price":1500,"gross_price":null,"unit":null,"e_invoicing":null,"price_with_tax":1500,"total_tax":0,"tax_ids":[],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created minimal item without taxes"},"With Tax":{"value":{"id":"item_6595a27b5d35015c3ef0c3fd","name":"EVA Toolkit - Standard","description":null,"translations":{},"price":2200,"gross_price":null,"unit":null,"e_invoicing":null,"price_with_tax":2684,"total_tax":484,"tax_ids":["tax_6595a27b5d35015c3ef0c3fd"],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created item with referenced tax (total_tax calculated)"},"With new tax":{"value":{"id":"item_6595a27b5d35015c3ef0c3fd","name":"Ground Station Antenna Array","description":null,"translations":{},"price":12500,"gross_price":null,"unit":null,"e_invoicing":null,"price_with_tax":15250,"total_tax":2750,"tax_ids":["tax_6595a27b5d35015c3ef0c3fd"],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created item with inline tax (tax created and referenced)"},"With Gross Price":{"value":{"id":"item_6595a27b5d35015c3ef0c3fd","name":"Thermal Shielding Panel","description":null,"translations":{},"price":850,"gross_price":1037,"unit":null,"e_invoicing":null,"price_with_tax":1037,"total_tax":187,"tax_ids":["tax_6595a27b5d35015c3ef0c3fd"],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created item with gross price - net price back-calculated from gross"},"With translations":{"value":{"id":"item_8595a27b5d35015c3ef0c3ff","name":"Mission Planning Services","description":"Monthly mission planning retainer","translations":{"name":{"de-DE":"Missionsplanungsleistungen"},"description":{"de-DE":"Monatlicher Missionsplanungs-Retainer"}},"price":1000,"gross_price":null,"unit":null,"e_invoicing":null,"price_with_tax":1000,"total_tax":0,"tax_ids":[],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created item with translated catalog-item content"},"Complete":{"value":{"id":"item_7595a27b5d35015c3ef0c3fe","name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","translations":{"name":{"de-DE":"Orbitale Navigationslizenz"},"description":{"de-DE":"Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"}},"price":5000,"gross_price":null,"unit":null,"e_invoicing":null,"price_with_tax":6100,"total_tax":1100,"tax_ids":["tax_6595a27b5d35015c3ef0c3fd"],"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{"category":"software","unit":"license"},"deleted_at":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z"},"description":"Created item with all optional fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/items/{id}/permanent":{"delete":{"operationId":"permanentDeleteItem","summary":"Permanently delete an item","description":"Permanently delete a soft-deleted item. Only items in the trash can be permanently deleted.","security":[{"Bearer":[]}],"tags":["Items"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Item permanently deleted"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments":{"post":{"operationId":"createPayment","summary":"Create a new payment","description":"Record a payment against an outgoing document or a supplier expense.\nAt least one document reference is required.\nFor new direct outgoing payments, prefer `document_id`; the API infers `invoice_id`, `credit_note_id`, or `advance_invoice_id` from the ID prefix.\nLegacy type-specific fields remain supported for backward compatibility.\nFor outgoing type `credit_note`, both `invoice_id` and `credit_note_id` are required.\nExpense payments support direct supplier invoice payments in V1; AP credit-note settlement is reserved for a later release.\nDocument payment totals are automatically updated.\nCredit note refunds or settlements cannot exceed the remaining credit balance.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Payments"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Create Payment Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"invoice_id":{"type":["string","null"],"maxLength":36},"credit_note_id":{"type":["string","null"],"maxLength":36},"advance_invoice_id":{"type":["string","null"],"maxLength":36},"expense_id":{"type":["string","null"],"maxLength":36},"applied_to_expense_id":{"type":["string","null"],"maxLength":36},"amount":{"type":"number","exclusiveMinimum":0,"description":"Payment amount in the linked document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents.","example":29.9},"type":{"type":"string","enum":["cash","bank_transfer","card","check","paypal","coupon","other","credit_note","advance"],"description":"Payment type/method"},"date":{"type":"string","description":"Payment date in YYYY-MM-DD format","example":"2024-01-15"},"tag":{"type":["string","null"],"maxLength":100},"reference":{"type":["string","null"],"maxLength":100},"note":{"type":["string","null"],"maxLength":500},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"document_id":{"type":["string","null"],"maxLength":36,"description":"Generic outgoing document ID for direct payments. The API infers `invoice_id`, `credit_note_id`, or `advance_invoice_id` from the ID prefix. Prefer this over type-specific fields for new integrations.","example":"cre_abc123"}},"required":["amount","type"],"additionalProperties":false},"examples":{"Minimal":{"value":{"invoice_id":"inv_abc123def456","amount":1500,"type":"cash"},"description":"Minimal payment with required fields only"},"With reference":{"value":{"invoice_id":"inv_abc123def456","amount":12500,"type":"bank_transfer","reference":"MSN-2025-001"},"description":"Payment with bank reference for tracking"},"Advance invoice payment":{"value":{"advance_invoice_id":"adv_abc123def456","amount":1000,"type":"bank_transfer","reference":"ADV-2025-001"},"description":"Record a payment against an advance invoice before it is applied to a final invoice."},"Credit note applied":{"value":{"invoice_id":"inv_abc123def456","credit_note_id":"cre_xyz789abc123","amount":850,"type":"credit_note","note":"Credit note applied for returned thermal panels"},"description":"Apply credit note balance to an invoice"},"Refund":{"value":{"credit_note_id":"cre_xyz789abc123","amount":2200,"type":"bank_transfer","reference":"ORB-2025-042-REF","note":"Refund for returned EVA toolkit"},"description":"Record refund payment against a credit note"},"Expense payment":{"value":{"expense_id":"exp_abc123def456","amount":122,"type":"bank_transfer","reference":"DE00-2025-001"},"description":"Direct payment recorded against a supplier expense"},"Complete":{"value":{"invoice_id":"inv_abc123def456","amount":12500,"type":"bank_transfer","date":"2024-01-10","reference":"ORB-2025-042","note":"First installment for antenna array","metadata":{"source":"web_app","processor":"stripe"}},"description":"Payment with all optional fields"}}}}},"responses":{"201":{"description":"Created Payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"},"examples":{"Minimal":{"value":{"id":"pmt_abc123def456","invoice_id":"inv_abc123def456","credit_note_id":null,"advance_invoice_id":null,"expense_id":null,"applied_to_expense_id":null,"amount":1500,"type":"cash","date":"2024-01-15T00:00:00.000Z","reference":null,"tag":null,"note":null,"entity_id":"ent_xyz789","metadata":{},"created_at":"2024-01-15T10:30:00.000Z","updated_at":"2024-01-15T10:30:00.000Z","deleted_at":null},"description":"Created minimal cash payment"},"With reference":{"value":{"id":"pmt_def789ghi012","invoice_id":"inv_abc123def456","credit_note_id":null,"advance_invoice_id":null,"expense_id":null,"applied_to_expense_id":null,"amount":12500,"type":"bank_transfer","date":"2024-01-10T00:00:00.000Z","reference":"MSN-2025-001","tag":null,"note":null,"entity_id":"ent_xyz789","metadata":{},"created_at":"2024-01-10T14:20:00.000Z","updated_at":"2024-01-10T14:20:00.000Z","deleted_at":null},"description":"Created bank transfer with reference"},"Credit note applied":{"value":{"id":"pmt_cn123abc456","invoice_id":"inv_abc123def456","credit_note_id":"cre_xyz789abc123","advance_invoice_id":null,"expense_id":null,"applied_to_expense_id":null,"amount":850,"type":"credit_note","date":"2024-01-20T00:00:00.000Z","reference":null,"tag":null,"note":"Credit note applied for returned thermal panels","entity_id":"ent_xyz789","metadata":{},"created_at":"2024-01-20T09:00:00.000Z","updated_at":"2024-01-20T09:00:00.000Z","deleted_at":null},"description":"Created credit note application"},"Refund":{"value":{"id":"pmt_ref456def789","invoice_id":null,"credit_note_id":"cre_xyz789abc123","advance_invoice_id":null,"expense_id":null,"applied_to_expense_id":null,"amount":2200,"type":"bank_transfer","date":"2024-01-22T00:00:00.000Z","reference":"ORB-2025-042-REF","tag":null,"note":"Refund for returned EVA toolkit","entity_id":"ent_xyz789","metadata":{},"created_at":"2024-01-22T11:30:00.000Z","updated_at":"2024-01-22T11:30:00.000Z","deleted_at":null},"description":"Created refund against credit note"},"Complete":{"value":{"id":"pmt_def789ghi012","invoice_id":"inv_abc123def456","credit_note_id":null,"advance_invoice_id":null,"expense_id":null,"applied_to_expense_id":null,"amount":12500,"type":"bank_transfer","date":"2024-01-10T00:00:00.000Z","reference":"ORB-2025-042","tag":null,"note":"First installment for antenna array","entity_id":"ent_xyz789","metadata":{"source":"web_app","processor":"stripe"},"created_at":"2024-01-10T14:20:00.000Z","updated_at":"2024-01-10T14:20:00.000Z","deleted_at":null},"description":"Created payment with all optional fields"},"Expense payment":{"value":{"id":"pmt_exp123abc456","invoice_id":null,"credit_note_id":null,"advance_invoice_id":null,"expense_id":"exp_abc123def456","applied_to_expense_id":null,"amount":122,"amount_converted":122,"currency_code":"EUR","type":"bank_transfer","date":"2024-01-15T00:00:00.000Z","reference":"DE00-2025-001","tag":null,"note":null,"entity_id":"ent_xyz789","metadata":{},"created_at":"2024-01-15T10:30:00.000Z","updated_at":"2024-01-15T10:30:00.000Z","deleted_at":null},"description":"Created direct expense payment"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getPayments","summary":"List all payments","description":"Retrieve a paginated list of payments with optional filtering and sorting. Supports cursor-based pagination, flexible JSON querying with MongoDB-style operators, full-text search, and sorting across both outgoing and expense payment references.","security":[{"Bearer":[]}],"tags":["Payments"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","amount","type","date","created_at","updated_at","-id","-amount","-type","-date","-created_at","-updated_at"]},{"type":"array","items":{"type":"string","enum":["id","amount","type","date","created_at","updated_at","-id","-amount","-type","-date","-created_at","-updated_at"]}}],"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, invoice_id, credit_note_id, advance_invoice_id, expense_id, applied_to_expense_id, amount, type, date, reference, note, metadata, created_at, updated_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, invoice_id, credit_note_id, advance_invoice_id, expense_id, applied_to_expense_id, amount, type, date, reference, note, metadata, created_at, updated_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"type":"string","description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","example":"Acme Corporation"},"required":false,"description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","name":"search","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `Invoice` - The invoice this payment is linked to\n- `CreditNote` - The credit note this payment is linked to\n- `AdvanceInvoice` - The advance invoice this payment is linked to\n- `Expense` - The expense this payment is linked to\n- `AppliedToExpense` - The supplier invoice expense this credit note settlement is applied to\n\n**Usage:**\n`?include=Invoice`\n`?include=Invoice,CreditNote,AdvanceInvoice,Expense,AppliedToExpense`","example":"Invoice"},"required":false,"description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `Invoice` - The invoice this payment is linked to\n- `CreditNote` - The credit note this payment is linked to\n- `AdvanceInvoice` - The advance invoice this payment is linked to\n- `Expense` - The expense this payment is linked to\n- `AppliedToExpense` - The supplier invoice expense this credit note settlement is applied to\n\n**Usage:**\n`?include=Invoice`\n`?include=Invoice,CreditNote,AdvanceInvoice,Expense,AppliedToExpense`","name":"include","in":"query"},{"schema":{"type":"boolean","description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items."},"required":false,"description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.","name":"deleted","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of Payments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"pmt_abc123def456","invoice_id":"inv_abc123def456","credit_note_id":null,"advance_invoice_id":null,"expense_id":null,"applied_to_expense_id":null,"amount":1500,"type":"cash","date":"2024-01-15T00:00:00.000Z","reference":null,"tag":null,"note":null,"entity_id":"ent_xyz789","metadata":{},"created_at":"2024-01-15T10:30:00.000Z","updated_at":"2024-01-15T10:30:00.000Z","deleted_at":null},{"id":"pmt_def789ghi012","invoice_id":"inv_abc123def456","credit_note_id":null,"advance_invoice_id":null,"expense_id":null,"applied_to_expense_id":null,"amount":12500,"type":"bank_transfer","date":"2024-01-10T00:00:00.000Z","reference":"ORB-2025-042","tag":null,"note":"First installment for antenna array","entity_id":"ent_xyz789","metadata":{"source":"web_app","processor":"stripe"},"created_at":"2024-01-10T14:20:00.000Z","updated_at":"2024-01-10T14:20:00.000Z","deleted_at":null}],"pagination":{"total":2,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of payments"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments/{id}":{"get":{"operationId":"getPaymentById","summary":"Get payment by ID","description":"Retrieve a single payment by its unique identifier. Returns the complete payment details including amount, type, date, and reference information.","security":[{"Bearer":[]}],"tags":["Payments"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `Invoice` - The invoice this payment is linked to\n- `CreditNote` - The credit note this payment is linked to\n- `AdvanceInvoice` - The advance invoice this payment is linked to\n- `Expense` - The expense this payment is linked to\n- `AppliedToExpense` - The supplier invoice expense this credit note settlement is applied to\n\n**Usage:**\n`?include=Invoice`\n`?include=Invoice,CreditNote,AdvanceInvoice,Expense,AppliedToExpense`","example":"Invoice"},"required":false,"description":"Comma-separated list of relations to include in the response.\n\n**Available relations:**\n- `Invoice` - The invoice this payment is linked to\n- `CreditNote` - The credit note this payment is linked to\n- `AdvanceInvoice` - The advance invoice this payment is linked to\n- `Expense` - The expense this payment is linked to\n- `AppliedToExpense` - The supplier invoice expense this credit note settlement is applied to\n\n**Usage:**\n`?include=Invoice`\n`?include=Invoice,CreditNote,AdvanceInvoice,Expense,AppliedToExpense`","name":"include","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Payment instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"},"examples":{"200":{"value":{"id":"pmt_def789ghi012","invoice_id":"inv_abc123def456","credit_note_id":null,"advance_invoice_id":null,"expense_id":null,"applied_to_expense_id":null,"amount":12500,"type":"bank_transfer","date":"2024-01-10T00:00:00.000Z","reference":"ORB-2025-042","tag":null,"note":"First installment for antenna array","entity_id":"ent_xyz789","metadata":{"source":"web_app","processor":"stripe"},"created_at":"2024-01-10T14:20:00.000Z","updated_at":"2024-01-10T14:20:00.000Z","deleted_at":null},"description":"Created payment with all optional fields"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updatePayment","summary":"Update a payment","description":"Update an existing payment.\nOnly the provided fields will be updated.\nDocument references cannot be changed.\nIf amount is changed, payment totals on all linked outgoing or incoming documents are automatically recalculated.\nSystem-managed settlement payments cannot be modified.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Payments"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Payment Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0,"description":"Payment amount in the linked document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents.","example":29.9},"type":{"type":"string","enum":["cash","bank_transfer","card","check","paypal","coupon","other","credit_note","advance"],"description":"Payment type/method"},"date":{"type":"string","description":"Payment date in YYYY-MM-DD format","example":"2024-01-15"},"tag":{"type":["string","null"],"maxLength":100},"reference":{"type":["string","null"],"maxLength":100},"note":{"type":["string","null"],"maxLength":500},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"additionalProperties":false},"examples":{"Update amount":{"value":{"amount":15000},"description":"Correct payment amount"},"Update note":{"value":{"note":"Final payment for ground station antenna array","reference":"MSN-2025-001-FINAL"},"description":"Add or update payment note and reference"}}}}},"responses":{"200":{"description":"Updated Payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"},"examples":{"Updated":{"value":{"id":"pmt_def789ghi012","invoice_id":"inv_abc123def456","credit_note_id":null,"advance_invoice_id":null,"amount":15000,"type":"bank_transfer","date":"2024-01-10T00:00:00.000Z","reference":"MSN-2025-001-FINAL","tag":null,"note":"Final payment for ground station antenna array","entity_id":"ent_xyz789","metadata":{},"created_at":"2024-01-10T14:20:00.000Z","updated_at":"2024-01-15T09:00:00.000Z","deleted_at":null},"description":"Updated payment record"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deletePayment","summary":"Delete a payment","description":"Soft delete a payment by its unique identifier. The payment is moved to trash and can be restored later. Payment totals on all linked outgoing or incoming documents are automatically recalculated after deletion. System-managed settlement payments remain immutable.","security":[{"Bearer":[]}],"tags":["Payments"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Payment deleted successfully"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments/{id}/restore":{"post":{"operationId":"restorePayment","summary":"Restore a deleted payment","description":"Restore a soft-deleted payment from the trash. Document payment totals are automatically recalculated.","security":[{"Bearer":[]}],"tags":["Payments"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Restored Payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"},"examples":{"200":{"value":{"id":"pmt_def789ghi012","invoice_id":"inv_abc123def456","credit_note_id":null,"advance_invoice_id":null,"expense_id":null,"applied_to_expense_id":null,"amount":12500,"type":"bank_transfer","date":"2024-01-10T00:00:00.000Z","reference":"ORB-2025-042","tag":null,"note":"First installment for antenna array","entity_id":"ent_xyz789","metadata":{"source":"web_app","processor":"stripe"},"created_at":"2024-01-10T14:20:00.000Z","updated_at":"2024-01-10T14:20:00.000Z","deleted_at":null},"description":"Created payment with all optional fields"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments/{id}/permanent":{"delete":{"operationId":"permanentDeletePayment","summary":"Permanently delete a payment","description":"Permanently delete a soft-deleted payment. Only payments in the trash can be permanently deleted. Document payment totals are automatically recalculated.","security":[{"Bearer":[]}],"tags":["Payments"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Payment permanently deleted"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/taxes":{"post":{"operationId":"createTax","summary":"Create a new tax","description":"Create a new tax with one or more tax rates.\nEach rate can specify a `valid_from` date to track historical changes (defaults to 1970-01-01 if not provided).\nRates are automatically sorted by `valid_from` date (newest first).","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Taxes"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Create Tax Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"tax_rates":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number","minimum":0,"maximum":100},"valid_from":{"type":["string","null"],"format":"date-time"}},"required":["rate"],"additionalProperties":false},"minItems":1},"is_default":{"type":"boolean","description":"Whether this is the default tax for new documents. Only one tax per entity can be default.","example":true},"classification":{"type":["string","null"],"description":"Classification for API tax lookups (e.g., \"standard\", \"reduced\", \"zero\"). Unique per entity. Can be used instead of rate when creating documents.","example":"standard"},"pt_exemption_code":{"type":["string","null"],"description":"Portugal exemption code for 0% / exempt / non-subject taxes.","example":"M13"},"pt_exemption_reason":{"type":["string","null"],"description":"Portugal exemption reason associated with pt_exemption_code.","example":"Regime da margem de lucro - Bens em segunda mao"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"required":["tax_rates"],"additionalProperties":false},"examples":{"Minimal":{"value":{"tax_rates":[{"rate":22}]},"description":"Tax with single rate (name defaults to '22%', valid_from defaults to 1970-01-01)"},"Classification lookup":{"value":{"name":"Standard VAT","classification":"standard","is_default":true,"tax_rates":[{"rate":22}]},"description":"Tax with a stable classification that document and item examples can reference instead of a rate."},"Portugal exemption":{"value":{"name":"PT exempt","classification":"zero","pt_exemption_code":"M13","pt_exemption_reason":"Regime da margem de lucro - Bens em segunda mao","tax_rates":[{"rate":0}]},"description":"Portuguese zero-rate/exempt tax with the SAF-T exemption code and reason."},"Complete":{"value":{"name":"Standard VAT","tax_rates":[{"rate":22}]},"description":"Tax with custom name instead of default rate-based name"}}}}},"responses":{"201":{"description":"Created Tax","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxResponse"},"examples":{"Minimal":{"value":{"id":"tax_6595a27b5d35015c3ef0c3fd","name":"22%","entity_id":"ent_6595a27b5d35015c3ef0c3fd","tax_rates":[{"rate":22,"valid_from":"1970-01-01T00:00:00.000Z"}],"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z","deleted_at":null},"description":"Created tax with default name '22%'"},"Complete":{"value":{"id":"tax_6595a27b5d35015c3ef0c3fe","name":"Standard VAT","entity_id":"ent_6595a27b5d35015c3ef0c3fd","tax_rates":[{"rate":22,"valid_from":"1970-01-01T00:00:00.000Z"}],"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z","deleted_at":null},"description":"Created tax with custom name"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getTaxes","summary":"List all taxes","description":"Retrieve a paginated list of taxes with optional filtering and sorting. Supports cursor-based pagination, flexible JSON querying with MongoDB-style operators, and sorting. Each tax may contain multiple historical rates.","security":[{"Bearer":[]}],"tags":["Taxes"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","name","created_at","updated_at","-id","-name","-created_at","-updated_at"]},{"type":"array","items":{"type":"string","enum":["id","name","created_at","updated_at","-id","-name","-created_at","-updated_at"]}}],"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, name, is_default, created_at, updated_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, name, is_default, created_at, updated_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"type":"string","description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","example":"Acme Corporation"},"required":false,"description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","name":"search","in":"query"},{"schema":{"type":"boolean","description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items."},"required":false,"description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.","name":"deleted","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of Taxes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"tax_6595a27b5d35015c3ef0c3fd","name":"22%","entity_id":"ent_6595a27b5d35015c3ef0c3fd","tax_rates":[{"rate":22,"valid_from":"1970-01-01T00:00:00.000Z"}],"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z","deleted_at":null},{"id":"tax_6595a27b5d35015c3ef0c3fe","name":"Standard VAT","entity_id":"ent_6595a27b5d35015c3ef0c3fd","tax_rates":[{"rate":22,"valid_from":"1970-01-01T00:00:00.000Z"}],"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z","deleted_at":null}],"pagination":{"total":2,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of taxes"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/taxes/{id}":{"patch":{"operationId":"updateTax","summary":"Add new tax rate(s)","description":"Add one or more new tax rates to an existing tax.\nNew rates are merged with existing rates and automatically sorted by `valid_from` date (newest first).\nUse this to track historical tax rate changes.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Taxes"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Tax Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_rates":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number","minimum":0,"maximum":100},"valid_from":{"type":["string","null"],"format":"date-time"}},"required":["rate"],"additionalProperties":false},"minItems":1},"is_default":{"type":"boolean","description":"Set to true to make this the default tax (unsets other defaults)","example":true}},"required":["tax_rates"],"additionalProperties":false},"examples":{"Add New Rate":{"value":{"tax_rates":[{"rate":25,"valid_from":"2025-01-01T00:00:00.000Z"}]},"description":"Add new tax rate(s) to existing tax (merged with existing rates and sorted)"}}}}},"responses":{"200":{"description":"Updated Tax","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxResponse"},"examples":{"Add New Rate":{"value":{"id":"tax_6595a27b5d35015c3ef0c3fd","name":"22%","entity_id":"ent_6595a27b5d35015c3ef0c3fd","tax_rates":[{"rate":25,"valid_from":"2025-01-01T00:00:00.000Z"},{"rate":22,"valid_from":"2024-01-01T00:00:00.000Z"},{"rate":20,"valid_from":"2020-01-01T00:00:00.000Z"}],"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2025-01-15T10:30:00.000Z","deleted_at":null},"description":"Updated tax with new rate added and all rates sorted"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"replaceTax","summary":"Replace tax rates","description":"Replace all tax rates on a tax with a new set of rates.\nThis completely replaces the existing `tax_rates` array.\nUse this when you need to remove rates or completely restructure the rate history.\nOptionally update the name as well.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Taxes"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Replace Tax Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"tax_rates":{"type":"array","items":{"type":"object","properties":{"rate":{"type":"number","minimum":0,"maximum":100},"valid_from":{"type":["string","null"],"format":"date-time"}},"required":["rate"],"additionalProperties":false},"minItems":1},"is_default":{"type":"boolean","description":"Whether this is the default tax for new documents. Only one tax per entity can be default.","example":true},"classification":{"type":["string","null"],"description":"Classification for API tax lookups (e.g., \"standard\", \"reduced\", \"zero\"). Unique per entity. Can be used instead of rate when creating documents.","example":"standard"},"pt_exemption_code":{"type":["string","null"],"description":"Portugal exemption code for 0% / exempt / non-subject taxes.","example":"M13"},"pt_exemption_reason":{"type":["string","null"],"description":"Portugal exemption reason associated with pt_exemption_code.","example":"Regime da margem de lucro - Bens em segunda mao"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"required":["tax_rates"],"additionalProperties":false},"examples":{"Replace Tax":{"value":{"name":"Updated VAT","tax_rates":[{"rate":21,"valid_from":"2025-01-01T00:00:00.000Z"},{"rate":19,"valid_from":"2020-01-01T00:00:00.000Z"}],"metadata":{"category":"vat","region":"EU"}},"description":"Replace all tax fields (name, rates, metadata). Name defaults to first rate if omitted."}}}}},"responses":{"200":{"description":"Replaced Tax","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxResponse"},"examples":{"Replace Tax":{"value":{"id":"tax_6595a27b5d35015c3ef0c3fd","name":"Updated VAT","entity_id":"ent_6595a27b5d35015c3ef0c3fd","tax_rates":[{"rate":21,"valid_from":"2025-01-01T00:00:00.000Z"},{"rate":19,"valid_from":"2020-01-01T00:00:00.000Z"}],"metadata":{"category":"vat","region":"EU"},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2025-01-15T10:30:00.000Z","deleted_at":null},"description":"Tax with all fields replaced"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteTax","summary":"Delete a tax","description":"Soft delete a tax. The tax will be moved to the trash and can be restored later.","security":[{"Bearer":[]}],"tags":["Taxes"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Tax deleted successfully"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/taxes/{id}/restore":{"post":{"operationId":"restoreTax","summary":"Restore a deleted tax","description":"Restore a soft-deleted tax from the trash.","security":[{"Bearer":[]}],"tags":["Taxes"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Restored Tax","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxResponse"},"examples":{"Minimal":{"value":{"id":"tax_6595a27b5d35015c3ef0c3fd","name":"22%","entity_id":"ent_6595a27b5d35015c3ef0c3fd","tax_rates":[{"rate":22,"valid_from":"1970-01-01T00:00:00.000Z"}],"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z","deleted_at":null},"description":"Created tax with default name '22%'"},"Complete":{"value":{"id":"tax_6595a27b5d35015c3ef0c3fe","name":"Standard VAT","entity_id":"ent_6595a27b5d35015c3ef0c3fd","tax_rates":[{"rate":22,"valid_from":"1970-01-01T00:00:00.000Z"}],"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z","deleted_at":null},"description":"Created tax with custom name"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/taxes/{id}/permanent":{"delete":{"operationId":"permanentDeleteTax","summary":"Permanently delete a tax","description":"Permanently delete a soft-deleted tax. Only taxes in the trash can be permanently deleted.","security":[{"Bearer":[]}],"tags":["Taxes"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Tax permanently deleted"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/upload/image":{"post":{"operationId":"uploadImage","summary":"Upload image","description":"Upload an image file to cloud storage.\nSupports PNG, JPG, WEBP, and GIF formats. Maximum file size: 5MB.\nImages are automatically optimized and stored in entity-specific folders.\nReturns secure URLs for use in entity settings, invoices, and other documents.","security":[{"Bearer":[]}],"tags":["Upload"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Image file to upload (PNG, JPG, WEBP, GIF)"}},"required":["file"]}}}},"responses":{"200":{"description":"Image uploaded successfully","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public URL of the uploaded image","example":"https://storage.example.com/si/entities/ent_123/logos/logo_ent_123_1741689600000.png"},"secure_url":{"type":"string","format":"uri","description":"Secure HTTPS URL of the uploaded image","example":"https://storage.example.com/si/entities/ent_123/logos/logo_ent_123_1741689600000.png"},"public_id":{"type":"string","description":"Storage object key for future reference/deletion","example":"si/entities/ent_123/logos/logo_ent_123_1741689600000.png"},"secureUrl":{"type":"string","format":"uri","deprecated":true,"description":"Deprecated compatibility alias for secure_url. Use secure_url for new integrations.","example":"https://storage.example.com/si/entities/ent_123/logos/logo_ent_123_1741689600000.png"},"publicId":{"type":"string","deprecated":true,"description":"Deprecated compatibility alias for public_id. Use public_id for new integrations.","example":"si/entities/ent_123/logos/logo_ent_123_1741689600000.png"},"format":{"type":"string","description":"Image format (jpg, png, webp, etc.)","example":"png"},"width":{"type":"number","description":"Image width in pixels","example":576},"height":{"type":"number","description":"Image height in pixels","example":192},"bytes":{"type":"number","description":"File size in bytes","example":45678},"entity_id":{"type":"string","description":"Entity ID that the image belongs to","example":"ent_507f1f77bcf86cd799439011"}},"required":["url","secureUrl","publicId","format","width","height","bytes","entity_id"]},"examples":{"Success":{"value":{"url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","secure_url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","public_id":"si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","secureUrl":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","publicId":"si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","format":"png","width":576,"height":192,"bytes":45678,"entity_id":"ent_507f1f77bcf86cd799439011","filename":"company-logo.png","mime_type":"image/png"},"description":"Successfully uploaded entity logo optimized for invoice display (576x192px, maintains aspect ratio)"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/files":{"post":{"operationId":"uploadFile","summary":"Upload a file","description":"Upload a file (logo, signature, or attachment) to cloud storage.\nFiles are automatically optimized and stored in entity-specific folders.\nLogos and signatures are entity-level (one per entity), while attachments can be associated with specific documents.","security":[{"Bearer":[]}],"tags":["Files"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"File to upload","format":"binary"},"category":{"type":"string","enum":["logo","signature","attachment"],"description":"File category (logo, signature, or attachment)","example":"logo"},"account_payable_id":{"type":"string","description":"Account payable ID for attachments (optional, only for attachment category)","example":"inv_abc123"},"business_unit_id":{"type":"string","description":"Business unit ID for logo/signature uploads.","example":"business_unit_abc123"},"expense_id":{"type":"string","description":"Expense ID for attachments (optional, only for attachment category)","example":"exp_abc123"}},"required":["category"]}}}},"responses":{"201":{"description":"File uploaded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileMetadata"},"examples":{"Logo":{"value":{"id":"file_6595a27b5d35015c3ef0c3fd","entity_id":"ent_507f1f77bcf86cd799439011","invoice_id":null,"estimate_id":null,"credit_note_id":null,"advance_invoice_id":null,"category":"logo","url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","secure_url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","public_id":"si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","secureUrl":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","publicId":"si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","format":"png","width":576,"height":192,"bytes":45678,"filename":"company-logo.png","mime_type":"image/png","metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"},"description":"Entity logo uploaded successfully"},"Signature":{"value":{"id":"file_6595a27b5d35015c3ef0c3fe","entity_id":"ent_507f1f77bcf86cd799439011","invoice_id":null,"estimate_id":null,"credit_note_id":null,"advance_invoice_id":null,"category":"signature","url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011_1741689600000.png","secure_url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011_1741689600000.png","public_id":"si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011_1741689600000.png","secureUrl":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011_1741689600000.png","publicId":"si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011_1741689600000.png","format":"png","width":400,"height":200,"bytes":23456,"filename":"signature.png","mime_type":"image/png","metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"},"description":"Entity signature uploaded successfully"},"Attachment":{"value":{"id":"file_6595a27b5d35015c3ef0c3ff","entity_id":"ent_507f1f77bcf86cd799439011","invoice_id":"inv_abc123def456","estimate_id":null,"credit_note_id":null,"advance_invoice_id":null,"category":"attachment","url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890.pdf","secure_url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890.pdf","public_id":"si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890.pdf","secureUrl":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890.pdf","publicId":"si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890.pdf","format":"pdf","width":null,"height":null,"bytes":245678,"filename":"invoice-receipt.pdf","mime_type":"application/pdf","metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"},"description":"Document attachment uploaded successfully"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getFiles","summary":"List all files","description":"Retrieve a paginated list of files for an entity.\nSupports filtering by category and optional document association.","security":[{"Bearer":[]}],"tags":["Files"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"type":"string","enum":["logo","signature","attachment"],"description":"Filter by file category","example":"logo"},"required":false,"description":"Filter by file category","name":"category","in":"query"},{"schema":{"type":"string","description":"Filter by account payable ID (for attachments)","example":"inv_abc123"},"required":false,"description":"Filter by account payable ID (for attachments)","name":"account_payable_id","in":"query"},{"schema":{"type":"string","description":"Filter by business unit ID","example":"business_unit_abc123"},"required":false,"description":"Filter by business unit ID","name":"business_unit_id","in":"query"},{"schema":{"type":"string","description":"Filter by expense ID (for attachments)","example":"exp_abc123"},"required":false,"description":"Filter by expense ID (for attachments)","name":"expense_id","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of Files","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FileMetadata"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"file_6595a27b5d35015c3ef0c3fd","entity_id":"ent_507f1f77bcf86cd799439011","invoice_id":null,"estimate_id":null,"credit_note_id":null,"advance_invoice_id":null,"category":"logo","url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","secure_url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","public_id":"si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","secureUrl":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","publicId":"si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","format":"png","width":576,"height":192,"bytes":45678,"filename":"company-logo.png","mime_type":"image/png","metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of files"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/files/{id}":{"get":{"operationId":"getFileById","summary":"Get file metadata by ID","description":"Retrieve file metadata by its unique identifier.","security":[{"Bearer":[]}],"tags":["Files"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"File metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileMetadata"},"examples":{"Logo":{"value":{"id":"file_6595a27b5d35015c3ef0c3fd","entity_id":"ent_507f1f77bcf86cd799439011","invoice_id":null,"estimate_id":null,"credit_note_id":null,"advance_invoice_id":null,"category":"logo","url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","secure_url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","public_id":"si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","secureUrl":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","publicId":"si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png","format":"png","width":576,"height":192,"bytes":45678,"filename":"company-logo.png","mime_type":"image/png","metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"},"description":"Entity logo uploaded successfully"},"Signature":{"value":{"id":"file_6595a27b5d35015c3ef0c3fe","entity_id":"ent_507f1f77bcf86cd799439011","invoice_id":null,"estimate_id":null,"credit_note_id":null,"advance_invoice_id":null,"category":"signature","url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011_1741689600000.png","secure_url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011_1741689600000.png","public_id":"si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011_1741689600000.png","secureUrl":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011_1741689600000.png","publicId":"si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011_1741689600000.png","format":"png","width":400,"height":200,"bytes":23456,"filename":"signature.png","mime_type":"image/png","metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"},"description":"Entity signature uploaded successfully"},"Attachment":{"value":{"id":"file_6595a27b5d35015c3ef0c3ff","entity_id":"ent_507f1f77bcf86cd799439011","invoice_id":"inv_abc123def456","estimate_id":null,"credit_note_id":null,"advance_invoice_id":null,"category":"attachment","url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890.pdf","secure_url":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890.pdf","public_id":"si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890.pdf","secureUrl":"https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890.pdf","publicId":"si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890.pdf","format":"pdf","width":null,"height":null,"bytes":245678,"filename":"invoice-receipt.pdf","mime_type":"application/pdf","metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"},"description":"Document attachment uploaded successfully"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteFile","summary":"Delete a file","description":"Delete a file and its metadata.\nThe file is removed from cloud storage and the database.","security":[{"Bearer":[]}],"tags":["Files"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"File deleted successfully"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/users/login":{"post":{"operationId":"login","summary":"Login user","description":"Authenticate a user with email and password. Returns an access token and the resolved user profile for the current brand or white-label origin.","tags":["Users"],"requestBody":{"description":"Login Credentials","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"],"additionalProperties":false},"example":{"email":"example@spaceinvoices.com","password":"SecurePass123!"}}}},"responses":{"200":{"description":"Access token created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponse"},"example":{"id":"token_live_e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","user_id":"6595a27b5d35015c3ef0c3fd","ttl":31536000,"scope":null,"impersonator_user_id":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z","user":{"id":"6595a27b5d35015c3ef0c3fd","email":"example@spaceinvoices.com","email_verified":false,"name":null,"account_id":null,"metadata":{},"settings":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/users/signup":{"post":{"operationId":"signup","summary":"Create user","description":"Create a new user account. For regular main-app signups this provisions an initial account membership unless a valid account invitation token joins the user to an existing account. White-label signups remain entity-user signups and ignore account invitation tokens.","tags":["Users"],"requestBody":{"description":"User Data","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":["string","null"],"minLength":2},"password":{"type":"string","minLength":8,"pattern":"[a-z]"},"settings":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}}]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"company_name":{"type":"string","minLength":1},"account_invitation_token":{"type":"string","minLength":1}},"required":["email","password"],"additionalProperties":false},"example":{"email":"example@spaceinvoices.com","password":"SecurePass123!"}}}},"responses":{"201":{"description":"Created user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedUser"},"example":{"id":"user_6595a27b5d35015c3ef0c3fd","email":"example@spaceinvoices.com","email_verified":false,"name":null,"account_id":null,"metadata":{},"settings":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/users/password-reset":{"post":{"operationId":"requestPasswordReset","summary":"Request password reset","description":"Request a password reset email. Always returns success to avoid email enumeration.","tags":["Users"],"requestBody":{"description":"Password reset request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"],"additionalProperties":false},"example":{"email":"example@spaceinvoices.com"}}}},"responses":{"200":{"description":"Password reset request accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordResetMessage"},"example":{"message":"If the account exists, password reset instructions have been sent."}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/users/password-reset/confirm":{"post":{"operationId":"confirmPasswordReset","summary":"Confirm password reset","description":"Reset a user password with a valid password reset token.","tags":["Users"],"requestBody":{"description":"Password reset confirmation","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":1},"password":{"type":"string","minLength":8,"pattern":"[a-z]"}},"required":["token","password"],"additionalProperties":false},"example":{"token":"prt_reset_token_123","password":"SecurePass123!"}}}},"responses":{"200":{"description":"Password reset complete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordResetMessage"},"example":{"message":"Password reset successful."}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/users/me/accounts":{"get":{"operationId":"listMyAccounts","summary":"List current user accounts","description":"Return the accounts the authenticated user belongs to, including display names and account-level roles.","security":[{"Bearer":[]}],"tags":["Users"],"responses":{"200":{"description":"User accounts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountsListResponse"},"examples":{"200":{"value":{"data":[{"id":"acc_123","name":"Space Invoices","role":"owner"},{"id":"acc_456","name":"Apollo","role":"member"}]}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/users/me":{"get":{"operationId":"getMe","summary":"Get current user","description":"Retrieve the authenticated user's profile information. Returns the user details associated with the provided Bearer token.","security":[{"Bearer":[]}],"tags":["Users"],"responses":{"200":{"description":"Authenticated User","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"examples":{"200":{"value":{"id":"6595a27b5d35015c3ef0c3fd","email":"example@spaceinvoices.com","email_verified":false,"name":null,"account_id":null,"metadata":{},"settings":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"patchMe","summary":"Update current user","description":"Update the authenticated user's profile. Currently supports updating the display name and preferred UI language (locale).","security":[{"Bearer":[]}],"tags":["Users"],"requestBody":{"description":"User Profile Update","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":["string","null"],"minLength":2,"description":"User display name","example":"John Doe"},"locale":{"type":["string","null"],"enum":["en","de","sl","it","fr","es","pt","nl","pl","hr","sv","fi","et","bg","cs","sk","nb","is",null],"description":"Preferred UI language. When omitted or null, the current preference is left unchanged.","example":"sl"}},"additionalProperties":false},"examples":{"Update locale":{"description":"Set preferred UI language","value":{"locale":"sl"}}}}}},"responses":{"200":{"description":"Updated User","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"examples":{"200":{"value":{"id":"6595a27b5d35015c3ef0c3fd","email":"example@spaceinvoices.com","email_verified":false,"name":null,"account_id":null,"metadata":{},"settings":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/users/me/account-deletion":{"post":{"operationId":"requestAccountDeletion","summary":"Request account deletion","description":"Immediately disables login and records a request to erase personal data that is not subject to statutory retention. Invoices and accounting records remain for the legally required period. Sign in with Apple authorization is revoked when a revocation token is available; provider failures are queued for retry without blocking the deletion request.","security":[{"Bearer":[]}],"tags":["Users"],"responses":{"202":{"description":"Account deletion requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountDeletionRequest"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/users/me/settings/furs":{"put":{"operationId":"updateUserFursSettings","summary":"Update user FURS operator settings","description":"Update FURS operator settings (tax number, label) for the current user. Settings are stored per-entity using the x-entity-id header. These settings are used when the user creates invoices through the web interface.","security":[{"Bearer":[]}],"tags":["Users"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"User FURS Settings","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operator_tax_number":{"type":"string","description":"Operator tax number for FURS fiscalization","example":"12345678"},"operator_label":{"type":"string","description":"Operator label/name for FURS fiscalization","example":"John Doe"}},"additionalProperties":false,"description":"Update user FURS operator settings for a specific entity"},"examples":{"Set operator info":{"description":"Set operator tax number and label for Slovenia FURS fiscalization","value":{"operator_tax_number":"12345678","operator_label":"Alex Carter"}}}}}},"responses":{"200":{"description":"Updated User","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"examples":{"200":{"value":{"id":"6595a27b5d35015c3ef0c3fd","email":"example@spaceinvoices.com","email_verified":false,"name":null,"account_id":null,"metadata":{},"settings":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/users/me/settings/fina":{"put":{"operationId":"updateUserFinaSettings","summary":"Update user FINA operator settings","description":"Update FINA operator settings (OIB, label) for the current user. Settings are stored per-entity using the x-entity-id header. These settings are used when the user creates invoices through the web interface.","security":[{"Bearer":[]}],"tags":["Users"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"User FINA Settings","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operator_oib":{"type":"string","description":"Operator OIB for FINA fiscalization","example":"12345678901"},"operator_label":{"type":"string","description":"Operator label/name for FINA fiscalization","example":"Ivan Horvat"}},"additionalProperties":false,"description":"Update user FINA operator settings for a specific entity"},"examples":{"Set operator info":{"description":"Set operator OIB and label for Croatia FINA fiscalization","value":{"operator_oib":"12345678901","operator_label":"Ivan Horvat"}}}}}},"responses":{"200":{"description":"Updated User","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"examples":{"200":{"value":{"id":"6595a27b5d35015c3ef0c3fd","email":"example@spaceinvoices.com","email_verified":false,"name":null,"account_id":null,"metadata":{},"settings":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/users/me/settings/pt":{"put":{"operationId":"updateUserPtSettings","summary":"Update user Portugal operator settings","description":"Update PT operator snapshot settings for the current user. Settings are stored per-entity using the x-entity-id header and used to auto-fill PT operator fields when the user creates PT documents.","security":[{"Bearer":[]}],"tags":["Users"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"User Portugal Settings","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operator_first_name":{"type":"string","description":"PT operator first name","example":"Joao"},"operator_last_name":{"type":"string","description":"PT operator last name","example":"Silva"},"operator_tax_number":{"type":"string","description":"PT operator tax number","example":"123456789"},"account_first_name":{"type":"string","description":"Deprecated alias for PT operator first name","example":"Joao"},"account_last_name":{"type":"string","description":"Deprecated alias for PT operator last name","example":"Silva"},"account_tax_number":{"type":"string","description":"Deprecated alias for PT operator tax number","example":"123456789"}},"additionalProperties":false,"description":"Update user PT operator settings for a specific entity"},"examples":{"Set operator info":{"description":"Set Portugal operator snapshot defaults for document creation","value":{"account_first_name":"Joao","account_last_name":"Silva","account_tax_number":"123456789"}}}}}},"responses":{"200":{"description":"Updated User","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"examples":{"200":{"value":{"id":"6595a27b5d35015c3ef0c3fd","email":"example@spaceinvoices.com","email_verified":false,"name":null,"account_id":null,"metadata":{},"settings":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers":{"post":{"operationId":"createCustomer","summary":"Create a new customer","description":"Create a new customer for use in invoices.\nStore customer details including name, address, and tax information.\nAll fields except name are optional.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Customers"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Create Customer Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"address":{"type":["string","null"],"maxLength":500},"address_2":{"type":["string","null"],"maxLength":500},"post_code":{"type":["string","null"],"maxLength":20},"city":{"type":["string","null"],"maxLength":100},"state":{"type":["string","null"],"maxLength":100},"country":{"type":["string","null"],"maxLength":100},"country_code":{"type":["string","null"],"maxLength":2},"tax_number":{"type":["string","null"],"maxLength":50},"company_number":{"type":["string","null"],"maxLength":50},"peppol_id":{"type":["string","null"],"maxLength":50},"peppol_scheme_id":{"type":["string","null"],"maxLength":10},"bank_accounts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/EntityBankAccount"}},"email":{"type":["string","null"],"maxLength":255},"contact_type":{"type":["string","null"],"enum":["buyer","supplier","both",null]},"is_tax_subject":{"type":"boolean"},"is_end_consumer":{"type":["boolean","null"]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpCustomerData"},{"type":"null"}]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"required":["name"],"additionalProperties":false},"examples":{"Minimal":{"value":{"name":"Alex Carter"},"description":"Minimal customer with only required fields"},"End consumer":{"value":{"name":"Retail customer","is_end_consumer":true},"description":"Retail/end-consumer customer record for B2C documents where business identifiers are not needed."},"EU business with VAT":{"value":{"name":"Orbital Systems GmbH","country":"Germany","country_code":"DE","tax_number":"DE123456789","is_tax_subject":true},"description":"EU business customer with VAT number for VIES and reverse-charge checks."},"PEPPOL recipient":{"value":{"name":"Občina Zelena Dolina","country":"Slovenia","country_code":"SI","tax_number":"SI12345679","company_number":"1234567890","peppol_id":"0088:1234567890128","peppol_scheme_id":"0208"},"description":"Customer with PEPPOL/e-invoicing identifier for e-SLOG and e-invoicing delivery flows."},"Complete":{"value":{"name":"Horizon Launch Systems Inc.","address":"100 Rocket Row","address_2":"Building 7","post_code":"77058","city":"Houston","state":"TX","country":"US","country_code":"US","tax_number":"74-1234567","is_tax_subject":true,"company_number":"0412345678","metadata":{"payment_terms":"Net 30","account_manager":"Mission Control"}},"description":"Complete customer with all optional fields"}}}}},"responses":{"201":{"description":"Created Customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"},"examples":{"Minimal":{"value":{"id":"cust_6595a27b5d35015c3ef0c3fd","name":"Alex Carter","email":null,"address":null,"address_2":null,"post_code":null,"city":null,"state":null,"country":null,"country_code":null,"tax_number":null,"is_tax_subject":true,"is_end_consumer":false,"company_number":null,"peppol_id":null,"peppol_scheme_id":null,"contact_type":"buyer","bank_accounts":null,"ujp":null,"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"vies":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Created minimal customer"},"Complete":{"value":{"id":"cust_7595a27b5d35015c3ef0c3fe","name":"Horizon Launch Systems Inc.","email":"procurement@horizonlaunch.example","address":"100 Rocket Row","address_2":"Building 7","post_code":"77058","city":"Houston","state":"TX","country":"US","country_code":"US","tax_number":"74-1234567","is_tax_subject":true,"is_end_consumer":false,"company_number":"0412345678","peppol_id":null,"peppol_scheme_id":null,"contact_type":"buyer","bank_accounts":null,"ujp":null,"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{"payment_terms":"Net 30","account_manager":"Mission Control"},"vies":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Created complete customer"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getCustomers","summary":"List all customers","description":"Retrieve a paginated list of customers with optional filtering and sorting.\nSupports cursor-based pagination, flexible JSON querying with MongoDB-style operators, full-text search, and sorting.","security":[{"Bearer":[]}],"tags":["Customers"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","name","email","address","city","country","created_at","updated_at","-id","-name","-email","-address","-city","-country","-created_at","-updated_at"]},{"type":"array","items":{"type":"string","enum":["id","name","email","address","city","country","created_at","updated_at","-id","-name","-email","-address","-city","-country","-created_at","-updated_at"]}}],"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, name, address, city, country, tax_number, email, contact_type, created_at, updated_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, name, address, city, country, tax_number, email, contact_type, created_at, updated_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"type":"string","description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","example":"Acme Corporation"},"required":false,"description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","name":"search","in":"query"},{"schema":{"type":"boolean","description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items."},"required":false,"description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.","name":"deleted","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of Customers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"cust_6595a27b5d35015c3ef0c3fd","name":"Alex Carter","email":null,"address":null,"address_2":null,"post_code":null,"city":null,"state":null,"country":null,"country_code":null,"tax_number":null,"is_tax_subject":true,"is_end_consumer":false,"company_number":null,"peppol_id":null,"peppol_scheme_id":null,"contact_type":"buyer","bank_accounts":null,"ujp":null,"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"vies":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of customers"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}":{"get":{"operationId":"getCustomerById","summary":"Get customer by ID","description":"Retrieve a single customer by its unique identifier.\nReturns the complete customer details including name, address, and tax information.","security":[{"Bearer":[]}],"tags":["Customers"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Customer instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"},"examples":{"200":{"value":{"id":"cust_7595a27b5d35015c3ef0c3fe","name":"Horizon Launch Systems Inc.","email":"procurement@horizonlaunch.example","address":"100 Rocket Row","address_2":"Building 7","post_code":"77058","city":"Houston","state":"TX","country":"US","country_code":"US","tax_number":"74-1234567","is_tax_subject":true,"is_end_consumer":false,"company_number":"0412345678","peppol_id":null,"peppol_scheme_id":null,"contact_type":"buyer","bank_accounts":null,"ujp":null,"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{"payment_terms":"Net 30","account_manager":"Mission Control"},"vies":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Created complete customer"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateCustomer","summary":"Update a customer","description":"Update an existing customer.\nOnly the provided fields will be updated.\nAll fields are optional for partial updates.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Customers"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Customer Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"address":{"type":["string","null"],"maxLength":500},"address_2":{"type":["string","null"],"maxLength":500},"post_code":{"type":["string","null"],"maxLength":20},"city":{"type":["string","null"],"maxLength":100},"state":{"type":["string","null"],"maxLength":100},"country":{"type":["string","null"],"maxLength":100},"country_code":{"type":["string","null"],"maxLength":2},"tax_number":{"type":["string","null"],"maxLength":50},"company_number":{"type":["string","null"],"maxLength":50},"peppol_id":{"type":["string","null"],"maxLength":50},"peppol_scheme_id":{"type":["string","null"],"maxLength":10},"bank_accounts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/EntityBankAccount"}},"email":{"type":["string","null"],"maxLength":255},"contact_type":{"type":["string","null"],"enum":["buyer","supplier","both",null]},"is_tax_subject":{"type":"boolean"},"is_end_consumer":{"type":["boolean","null"]},"ujp":{"anyOf":[{"$ref":"#/components/schemas/UjpCustomerData"},{"type":"null"}]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"additionalProperties":false},"examples":{"Update name":{"value":{"name":"Horizon Launch Systems LLC"},"description":"Update customer name"},"Update address":{"value":{"address":"200 Orbit Drive","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"US","country_code":"US"},"description":"Update customer address fields"}}}}},"responses":{"200":{"description":"Updated Customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"},"examples":{"Updated":{"value":{"id":"cust_7595a27b5d35015c3ef0c3fe","name":"Horizon Launch Systems Inc.","email":"procurement@horizonlaunch.example","address":"100 Rocket Row","address_2":"Building 7","post_code":"77058","city":"Houston","state":"TX","country":"US","country_code":"US","tax_number":"74-1234567","is_tax_subject":true,"is_end_consumer":false,"company_number":"0412345678","peppol_id":null,"peppol_scheme_id":null,"contact_type":"buyer","bank_accounts":null,"ujp":null,"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{"payment_terms":"Net 30","account_manager":"Mission Control"},"vies":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Created complete customer"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteCustomer","summary":"Delete a customer","description":"Soft delete a customer by its unique identifier. The customer is moved to the trash and can be restored.","security":[{"Bearer":[]}],"tags":["Customers"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Customer deleted successfully"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}/restore":{"post":{"operationId":"restoreCustomer","summary":"Restore a deleted customer","description":"Restore a soft-deleted customer from the trash.","security":[{"Bearer":[]}],"tags":["Customers"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Restored Customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"},"examples":{"200":{"value":{"id":"cust_7595a27b5d35015c3ef0c3fe","name":"Horizon Launch Systems Inc.","email":"procurement@horizonlaunch.example","address":"100 Rocket Row","address_2":"Building 7","post_code":"77058","city":"Houston","state":"TX","country":"US","country_code":"US","tax_number":"74-1234567","is_tax_subject":true,"is_end_consumer":false,"company_number":"0412345678","peppol_id":null,"peppol_scheme_id":null,"contact_type":"buyer","bank_accounts":null,"ujp":null,"entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{"payment_terms":"Net 30","account_manager":"Mission Control"},"vies":null,"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Created complete customer"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/customers/{id}/permanent":{"delete":{"operationId":"permanentDeleteCustomer","summary":"Permanently delete a customer","description":"Permanently delete a soft-deleted customer. Only customers in the trash can be permanently deleted.","security":[{"Bearer":[]}],"tags":["Customers"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Customer permanently deleted"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses":{"post":{"operationId":"createExpense","summary":"Create expense","description":"This is the recommended endpoint for normal expense creation. Use it when Space Invoices should validate the supplied totals, tax summaries, and line items, then apply supplier handling, payment tracking initialization, and lifecycle rules.","security":[{"Bearer":[]}],"x-codegen-request-body-name":"data","tags":["Expenses"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"description":"Create Expense Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["invoice"],"default":"invoice","description":"Expense document type. Optional — defaults to `invoice` (the only value supported in V1; AP credit notes and advance invoices are reserved for a later version)."},"is_draft":{"type":["boolean","null"],"default":false,"description":"Whether to save the expense as an incomplete draft. Defaults to false."},"supplier_id":{"type":["string","null"]},"supplier":{"anyOf":[{"$ref":"#/components/schemas/ExpenseSupplier"},{"type":"null"}]},"save_supplier":{"type":["boolean","null"],"description":"Whether to save supplier data to the contact directory. When `supplier` is provided, this defaults to true. On update, `save_supplier: true` without a `supplier` object re-applies the expense's stored supplier snapshot to the linked contact."},"supplier_document_number":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"The supplier's own invoice number as printed on their document. Used for duplicate awareness (unique per supplier for active expenses) and accounting exports.","example":"AP-2024-0417"},"date":{"type":["string","null"],"format":"date"},"date_received":{"type":["string","null"],"format":"date"},"date_due":{"type":["string","null"],"format":"date"},"date_service":{"type":["string","null"],"format":"date"},"date_service_to":{"type":["string","null"],"format":"date"},"currency_code":{"type":["string","null"],"minLength":3,"maxLength":3},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export",null]},"reference":{"type":["string","null"],"maxLength":100},"note":{"type":["string","null"],"maxLength":2000},"items":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateExpenseItem"},"description":"Optional line items. Provide either `price` (net) or `gross_price` per line (not both); the server computes line totals. Per-line taxes take a rate only, e.g. `taxes: [{ rate: 22 }]`. Omit `items` for a summary-only (quick) expense and send document `total`/`total_with_tax` + `taxes` instead."},"taxes":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ExpenseSummaryTax"}},"total":{"type":["number","null"]},"total_with_tax":{"type":["number","null"]},"total_discount":{"type":["number","null"]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"payments":{"type":["array","null"],"items":{"type":"object","properties":{"amount":{"type":["number","null"],"exclusiveMinimum":0,"description":"Payment amount in the document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. If omitted, the document total (`total_with_tax`) is used."},"date":{"type":["string","null"],"description":"Payment date in YYYY-MM-DD format. Defaults to today.","example":"2024-01-15"},"tag":{"type":["string","null"]},"reference":{"type":["string","null"]},"note":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"type":{"type":"string","enum":["cash","bank_transfer","card","check","paypal","coupon","other","advance"]}},"required":["type"],"additionalProperties":false},"description":"Optional payments to record with the expense. If amounts are omitted, the remaining total_with_tax is split equally. Automatically updates expense payment status."},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"exchange_rate":{"anyOf":[{"$ref":"#/components/schemas/ExchangeRate"},{"type":"null"}]},"summary_classification":{"anyOf":[{"$ref":"#/components/schemas/ExpenseSummaryClassification"},{"type":"null"}]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"additionalProperties":false},"examples":{"Minimal":{"value":{"supplier":{"name":"Office Supplies Ltd","tax_number":"SI12345678","country_code":"SI"},"supplier_document_number":"2025-0417","date":"2025-10-03","total":100,"total_with_tax":122,"taxes":[{"rate":22,"base":100,"amount":22}]},"description":"Smallest useful final expense: supplier, supplier document reference, date, and summary totals. Document type, final status, currency, received date, transaction type, and input VAT deductibility use their defaults."},"Summary-only":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"AP-CUSTOM-001","date":"2025-10-03","summary_classification":"service","taxes":[{"rate":19,"base":45.22,"amount":8.59},{"rate":0,"base":125.63,"amount":0}],"total":170.85,"total_with_tax":179.44,"note":"Supplier provided totals only"},"description":"Summary-only document for OCR/manual totals without item lines"},"Reverse-charge not deductible":{"value":{"supplier":{"name":"EU Supplier GmbH","country_code":"DE","tax_number":"DE123456789"},"supplier_document_number":"EU-RC-2025-001","date":"2025-10-03","summary_classification":"service","taxes":[{"rate":22,"base":100,"amount":22,"is_deductible":false,"reverse_charge":true}],"total":100,"total_with_tax":100},"description":"Record self-assessed VAT where the reverse-charge tax is tracked for accounting but is not added to the payable total."},"Complete":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"OPS-2025-001","date":"2025-10-03","date_due":"2025-11-02","reference":"DE00-2025-001","note":"Ground facility maintenance — March billing period","items":[{"name":"Ground facility maintenance","description":"Monthly ground facility maintenance","quantity":1,"unit":"service","classification":"service","price":100,"taxes":[{"rate":19}],"total":100,"total_with_tax":119}],"taxes":[{"rate":19,"base":100,"amount":19}],"total":100,"total_with_tax":119},"description":"Posted incoming invoice with item lines and tax summary"},"By supplier id":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"OPS-2025-010","date":"2025-10-03","date_received":"2025-10-04","date_due":"2025-11-02","currency_code":"EUR","total":200,"total_with_tax":244,"taxes":[{"rate":22,"base":200,"amount":44}]},"description":"Reference an existing contact by `supplier_id` instead of sending a supplier snapshot."},"Multiple tax rates":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"AP-2025-0099","date":"2025-10-03","summary_classification":"product","taxes":[{"rate":22,"base":45.22,"amount":9.95},{"rate":9.5,"base":100,"amount":9.5},{"rate":0,"base":25.63,"amount":0}],"total":170.85,"total_with_tax":190.3},"description":"Summary-only expense split across several VAT rates (standard, reduced, and zero-rated)."},"Itemized (gross prices)":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"OPS-2025-011","date":"2025-10-03","items":[{"name":"Taxi fare","quantity":1,"classification":"service","gross_price":24.4,"taxes":[{"rate":22}],"total":20,"total_with_tax":24.4}]},"description":"Itemized line entered as a tax-inclusive `gross_price` (instead of `price`); the server derives the net."},"Non-deductible VAT":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"AP-REP-2025-004","date":"2025-10-03","summary_classification":"service","taxes":[{"rate":22,"base":100,"amount":22,"is_deductible":false}],"total":100,"total_with_tax":122,"note":"Representation costs — input VAT not deductible"},"description":"Mark a tax line as non-deductible (`is_deductible: false`) for AP bookkeeping."},"Partially deductible VAT":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"AP-PARTIAL-2025-005","date":"2025-10-03","summary_classification":"service","taxes":[{"rate":22,"base":100,"amount":22,"deductible_percentage":50}],"total":100,"total_with_tax":122,"note":"Half of input VAT is deductible"},"description":"Use `deductible_percentage` for partial input VAT recovery. The response keeps `is_deductible` for compatibility."},"Marked paid on creation":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"AP-2025-0120","date":"2025-10-03","date_due":"2025-11-02","total":100,"total_with_tax":122,"taxes":[{"rate":22,"base":100,"amount":22}],"payments":[{"type":"bank_transfer","amount":122}]},"description":"Record a payment together with the expense; omit `amount` to split the remaining total equally across payments."},"Foreign currency":{"value":{"supplier":{"name":"US Software Inc.","country_code":"US","tax_number":"12-3456789"},"supplier_document_number":"US-2025-0007","date":"2025-10-03","currency_code":"USD","total":500,"total_with_tax":500,"taxes":[{"rate":0,"base":500,"amount":0}]},"description":"A non-home-currency expense; the exchange rate is fetched and converted totals are stored alongside the originals."},"Draft":{"value":{"is_draft":true,"supplier":{"name":"Draft Supplier d.o.o."},"note":"OCR draft pending review"},"description":"Incomplete draft that can be enriched later by OCR or manual entry."}}}}},"responses":{"201":{"description":"Created expense","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Expense"},"examples":{"Minimal":{"value":{"id":"exp_9595a27b5d35015c3ef0c400","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":null,"type":"invoice","is_draft":false,"voided_at":null,"supplier":{"name":"Office Supplies Ltd","tax_number":"SI12345678","country_code":"SI"},"supplier_document_number":"2025-0417","date":"2025-10-03","date_received":"2025-10-03","date_due":null,"date_service":null,"date_service_to":null,"currency_code":"EUR","transaction_type":"domestic","reference":"DE00-2025-001","note":null,"summary_classification":null,"items":[],"taxes":[{"rate":22,"base":100,"amount":22,"is_deductible":true,"deductible_percentage":100}],"total":100,"total_with_tax":122,"total_discount":0,"total_paid":0,"total_due":122,"paid_in_full":false,"exchange_rate":null,"attachment_count":0,"has_attachment":false,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-04T08:00:00.000Z"},"description":"Created final summary expense"},"Summary-only":{"value":{"id":"exp_7595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":"sup_6595a27b5d35015c3ef0c3fd","type":"invoice","is_draft":false,"voided_at":null,"supplier":{"name":"Orbital Power Systems GmbH","address":"Energieweg 8","address_2":null,"post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","tax_number":"DE987654321","company_number":"HRB 98765","email":"accounts@orbital-power.example","phone":"+493012345678","peppol_id":"0088:9876543210982","is_tax_subject":true},"supplier_document_number":"AP-CUSTOM-001","date":"2025-10-03","date_received":"2025-10-03","date_due":"2025-11-02","date_service":null,"date_service_to":null,"currency_code":"EUR","transaction_type":"domestic","reference":"DE00-2025-001","note":"Supplier provided totals only","summary_classification":"service","items":[],"taxes":[{"rate":19,"base":45.22,"amount":8.59,"is_deductible":true,"deductible_percentage":100,"reverse_charge":false},{"rate":0,"base":125.63,"amount":0,"is_deductible":true,"deductible_percentage":100,"reverse_charge":false}],"total":170.85,"total_with_tax":179.44,"total_discount":0,"total_paid":0,"total_due":179.44,"paid_in_full":false,"exchange_rate":null,"attachment_count":0,"has_attachment":false,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-04T08:00:00.000Z"},"description":"Created summary-only incoming invoice"},"Complete":{"value":{"id":"exp_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":"sup_6595a27b5d35015c3ef0c3fd","type":"invoice","is_draft":false,"voided_at":null,"supplier":{"name":"Orbital Power Systems GmbH","address":"Energieweg 8","address_2":null,"post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","tax_number":"DE987654321","company_number":"HRB 98765","email":"accounts@orbital-power.example","phone":"+493012345678","peppol_id":"0088:9876543210982","is_tax_subject":true},"supplier_document_number":"OPS-2025-001","date":"2025-10-03","date_received":"2025-10-03","date_due":"2025-11-02","date_service":null,"date_service_to":null,"currency_code":"EUR","transaction_type":"domestic","reference":"DE00-2025-001","note":"Ground facility maintenance — March billing period","summary_classification":null,"items":[{"name":"Ground facility maintenance","description":"Monthly ground facility maintenance","quantity":1,"unit":"service","classification":"service","price":100,"gross_price":119,"discounts":[],"taxes":[{"rate":19,"amount":19,"is_deductible":true,"deductible_percentage":100}],"total":100,"total_with_tax":119,"total_tax":19}],"taxes":[{"rate":19,"base":100,"amount":19,"is_deductible":true,"deductible_percentage":100,"reverse_charge":false}],"total":100,"total_with_tax":119,"total_discount":0,"total_paid":0,"total_due":119,"paid_in_full":false,"exchange_rate":null,"attachment_count":1,"has_attachment":true,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-03T08:00:00.000Z"},"description":"Created posted incoming invoice"},"Draft":{"value":{"id":"exp_8595a27b5d35015c3ef0c3ff","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":null,"type":"invoice","is_draft":true,"voided_at":null,"supplier":{"name":"Orbital Power Systems GmbH","address":"Energieweg 8","address_2":null,"post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","tax_number":"DE987654321","company_number":"HRB 98765","email":"accounts@orbital-power.example","phone":"+493012345678","peppol_id":"0088:9876543210982","is_tax_subject":true},"supplier_document_number":null,"date":null,"date_received":null,"date_due":null,"date_service":null,"date_service_to":null,"currency_code":null,"transaction_type":null,"reference":"DE00-2025-001","note":"OCR draft pending review","summary_classification":null,"items":[],"taxes":[],"total":null,"total_with_tax":null,"total_discount":0,"total_paid":0,"total_due":0,"paid_in_full":false,"exchange_rate":null,"attachment_count":0,"has_attachment":false,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-03T08:00:00.000Z"},"description":"Created draft expense"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Duplicate supplier document number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseDuplicateConflictError"},"examples":{"Duplicate supplier document":{"value":{"code":"conflict","message":"An expense for this supplier with the same document number already exists","conflicting_expense_id":"exp_6595a27b5d35015c3ef0c3fd"},"description":"Another active expense for the supplier already uses this supplier document number."}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getExpenses","summary":"List expenses","description":"Retrieve a paginated list of expenses with optional filtering.\nSupports cursor-based pagination, full-text search across supplier snapshot and document fields, and suite-standard JSON query filters for date, totals, payment state, and supplier snapshot data.","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"type":"boolean","description":"Filter expenses by whether at least one attachment exists."},"required":false,"description":"Filter expenses by whether at least one attachment exists.","name":"has_attachment","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, number, type, is_draft, voided_at, deleted_at, supplier_id, supplier, supplier_document_number, date, date_received, date_due, date_service, date_service_to, currency_code, transaction_type, reference, note, summary_classification, total, total_with_tax, total_paid, total_due, paid_in_full, created_at, updated_at, metadata\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, number, type, is_draft, voided_at, deleted_at, supplier_id, supplier, supplier_document_number, date, date_received, date_due, date_service, date_service_to, currency_code, transaction_type, reference, note, summary_classification, total, total_with_tax, total_paid, total_due, paid_in_full, created_at, updated_at, metadata\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","date","date_received","date_due","total_due","created_at","-id","-date","-date_received","-date_due","-total_due","-created_at"]},{"type":"array","items":{"type":"string","enum":["id","date","date_received","date_due","total_due","created_at","-id","-date","-date_received","-date_due","-total_due","-created_at"]}}],"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","example":"Acme Corporation"},"required":false,"description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","name":"search","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of expenses","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Expense"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"Default":{"value":{"data":[{"id":"exp_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":"sup_6595a27b5d35015c3ef0c3fd","type":"invoice","is_draft":false,"voided_at":null,"supplier":{"name":"Orbital Power Systems GmbH","address":"Energieweg 8","address_2":null,"post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","tax_number":"DE987654321","company_number":"HRB 98765","email":"accounts@orbital-power.example","phone":"+493012345678","peppol_id":"0088:9876543210982","is_tax_subject":true},"supplier_document_number":"OPS-2025-001","date":"2025-10-03","date_received":"2025-10-03","date_due":"2025-11-02","date_service":null,"date_service_to":null,"currency_code":"EUR","transaction_type":"domestic","reference":"DE00-2025-001","note":"Ground facility maintenance — March billing period","summary_classification":null,"items":[{"name":"Ground facility maintenance","description":"Monthly ground facility maintenance","quantity":1,"unit":"service","classification":"service","price":100,"gross_price":119,"discounts":[],"taxes":[{"rate":19,"amount":19,"is_deductible":true,"deductible_percentage":100}],"total":100,"total_with_tax":119,"total_tax":19}],"taxes":[{"rate":19,"base":100,"amount":19,"is_deductible":true,"deductible_percentage":100,"reverse_charge":false}],"total":100,"total_with_tax":119,"total_discount":0,"total_paid":0,"total_due":119,"paid_in_full":false,"exchange_rate":null,"attachment_count":1,"has_attachment":true,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-03T08:00:00.000Z"},{"id":"exp_7595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":"sup_6595a27b5d35015c3ef0c3fd","type":"invoice","is_draft":false,"voided_at":null,"supplier":{"name":"Orbital Power Systems GmbH","address":"Energieweg 8","address_2":null,"post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","tax_number":"DE987654321","company_number":"HRB 98765","email":"accounts@orbital-power.example","phone":"+493012345678","peppol_id":"0088:9876543210982","is_tax_subject":true},"supplier_document_number":"AP-CUSTOM-001","date":"2025-10-03","date_received":"2025-10-03","date_due":"2025-11-02","date_service":null,"date_service_to":null,"currency_code":"EUR","transaction_type":"domestic","reference":"DE00-2025-001","note":"Supplier provided totals only","summary_classification":"service","items":[],"taxes":[{"rate":19,"base":45.22,"amount":8.59,"is_deductible":true,"deductible_percentage":100,"reverse_charge":false},{"rate":0,"base":125.63,"amount":0,"is_deductible":true,"deductible_percentage":100,"reverse_charge":false}],"total":170.85,"total_with_tax":179.44,"total_discount":0,"total_paid":0,"total_due":179.44,"paid_in_full":false,"exchange_rate":null,"attachment_count":0,"has_attachment":false,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-04T08:00:00.000Z"}],"pagination":{"total":2,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of expenses"},"Search":{"value":{"data":[{"id":"exp_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":"sup_6595a27b5d35015c3ef0c3fd","type":"invoice","is_draft":false,"voided_at":null,"supplier":{"name":"Orbital Power Systems GmbH","address":"Energieweg 8","address_2":null,"post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","tax_number":"DE987654321","company_number":"HRB 98765","email":"accounts@orbital-power.example","phone":"+493012345678","peppol_id":"0088:9876543210982","is_tax_subject":true},"supplier_document_number":"OPS-2025-001","date":"2025-10-03","date_received":"2025-10-03","date_due":"2025-11-02","date_service":null,"date_service_to":null,"currency_code":"EUR","transaction_type":"domestic","reference":"DE00-2025-001","note":"Ground facility maintenance — March billing period","summary_classification":null,"items":[{"name":"Ground facility maintenance","description":"Monthly ground facility maintenance","quantity":1,"unit":"service","classification":"service","price":100,"gross_price":119,"discounts":[],"taxes":[{"rate":19,"amount":19,"is_deductible":true,"deductible_percentage":100}],"total":100,"total_with_tax":119,"total_tax":19}],"taxes":[{"rate":19,"base":100,"amount":19,"is_deductible":true,"deductible_percentage":100,"reverse_charge":false}],"total":100,"total_with_tax":119,"total_discount":0,"total_paid":0,"total_due":119,"paid_in_full":false,"exchange_rate":null,"attachment_count":1,"has_attachment":true,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-03T08:00:00.000Z"}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Example search result for `?search=Orbital Power` or filtered query result such as `{\"supplier\":{\"name\":{\"contains\":\"Orbital\"}}}`."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/custom":{"post":{"operationId":"createCustomExpense","summary":"Create expense with pre-calculated totals","description":"Advanced endpoint for importing expenses that already have authoritative pre-calculated totals. Do not use this for normal expense creation. Prefer the standard create endpoint unless your integration must preserve exact external totals from an ERP, OCR, migration, or accounting system.\nThe caller provides document totals, item totals, and tax summaries directly.\nThe persistence, supplier handling, payment tracking initialization, and lifecycle rules are identical to the standard create endpoint.","security":[{"Bearer":[]}],"x-codegen-request-body-name":"data","tags":["Expenses"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"description":"Custom Expense Request","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomExpenseWrite"},"examples":{"Minimal":{"value":{"supplier":{"name":"Office Supplies Ltd","tax_number":"SI12345678","country_code":"SI"},"supplier_document_number":"2025-0417","date":"2025-10-03","total":100,"total_with_tax":122,"taxes":[{"rate":22,"base":100,"amount":22}]},"description":"Smallest useful final expense: supplier, supplier document reference, date, and summary totals. Document type, final status, currency, received date, transaction type, and input VAT deductibility use their defaults."},"Summary-only":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"AP-CUSTOM-001","date":"2025-10-03","summary_classification":"service","taxes":[{"rate":19,"base":45.22,"amount":8.59},{"rate":0,"base":125.63,"amount":0}],"total":170.85,"total_with_tax":179.44,"note":"Supplier provided totals only"},"description":"Summary-only document for OCR/manual totals without item lines"},"Reverse-charge not deductible":{"value":{"supplier":{"name":"EU Supplier GmbH","country_code":"DE","tax_number":"DE123456789"},"supplier_document_number":"EU-RC-2025-001","date":"2025-10-03","summary_classification":"service","taxes":[{"rate":22,"base":100,"amount":22,"is_deductible":false,"reverse_charge":true}],"total":100,"total_with_tax":100},"description":"Record self-assessed VAT where the reverse-charge tax is tracked for accounting but is not added to the payable total."},"Complete":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"OPS-2025-001","date":"2025-10-03","date_due":"2025-11-02","reference":"DE00-2025-001","note":"Ground facility maintenance — March billing period","items":[{"name":"Ground facility maintenance","description":"Monthly ground facility maintenance","quantity":1,"unit":"service","classification":"service","price":100,"taxes":[{"rate":19}],"total":100,"total_with_tax":119}],"taxes":[{"rate":19,"base":100,"amount":19}],"total":100,"total_with_tax":119},"description":"Posted incoming invoice with item lines and tax summary"},"By supplier id":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"OPS-2025-010","date":"2025-10-03","date_received":"2025-10-04","date_due":"2025-11-02","currency_code":"EUR","total":200,"total_with_tax":244,"taxes":[{"rate":22,"base":200,"amount":44}]},"description":"Reference an existing contact by `supplier_id` instead of sending a supplier snapshot."},"Multiple tax rates":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"AP-2025-0099","date":"2025-10-03","summary_classification":"product","taxes":[{"rate":22,"base":45.22,"amount":9.95},{"rate":9.5,"base":100,"amount":9.5},{"rate":0,"base":25.63,"amount":0}],"total":170.85,"total_with_tax":190.3},"description":"Summary-only expense split across several VAT rates (standard, reduced, and zero-rated)."},"Itemized (gross prices)":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"OPS-2025-011","date":"2025-10-03","items":[{"name":"Taxi fare","quantity":1,"classification":"service","gross_price":24.4,"taxes":[{"rate":22}],"total":20,"total_with_tax":24.4}]},"description":"Itemized line entered as a tax-inclusive `gross_price` (instead of `price`); the server derives the net."},"Non-deductible VAT":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"AP-REP-2025-004","date":"2025-10-03","summary_classification":"service","taxes":[{"rate":22,"base":100,"amount":22,"is_deductible":false}],"total":100,"total_with_tax":122,"note":"Representation costs — input VAT not deductible"},"description":"Mark a tax line as non-deductible (`is_deductible: false`) for AP bookkeeping."},"Partially deductible VAT":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"AP-PARTIAL-2025-005","date":"2025-10-03","summary_classification":"service","taxes":[{"rate":22,"base":100,"amount":22,"deductible_percentage":50}],"total":100,"total_with_tax":122,"note":"Half of input VAT is deductible"},"description":"Use `deductible_percentage` for partial input VAT recovery. The response keeps `is_deductible` for compatibility."},"Marked paid on creation":{"value":{"supplier_id":"cus_6595a27b5d35015c3ef0c3fd","supplier_document_number":"AP-2025-0120","date":"2025-10-03","date_due":"2025-11-02","total":100,"total_with_tax":122,"taxes":[{"rate":22,"base":100,"amount":22}],"payments":[{"type":"bank_transfer","amount":122}]},"description":"Record a payment together with the expense; omit `amount` to split the remaining total equally across payments."},"Foreign currency":{"value":{"supplier":{"name":"US Software Inc.","country_code":"US","tax_number":"12-3456789"},"supplier_document_number":"US-2025-0007","date":"2025-10-03","currency_code":"USD","total":500,"total_with_tax":500,"taxes":[{"rate":0,"base":500,"amount":0}]},"description":"A non-home-currency expense; the exchange rate is fetched and converted totals are stored alongside the originals."},"Draft":{"value":{"is_draft":true,"supplier":{"name":"Draft Supplier d.o.o."},"note":"OCR draft pending review"},"description":"Incomplete draft that can be enriched later by OCR or manual entry."}}}}},"responses":{"201":{"description":"Created expense","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Expense"},"examples":{"Minimal":{"value":{"id":"exp_9595a27b5d35015c3ef0c400","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":null,"type":"invoice","is_draft":false,"voided_at":null,"supplier":{"name":"Office Supplies Ltd","tax_number":"SI12345678","country_code":"SI"},"supplier_document_number":"2025-0417","date":"2025-10-03","date_received":"2025-10-03","date_due":null,"date_service":null,"date_service_to":null,"currency_code":"EUR","transaction_type":"domestic","reference":"DE00-2025-001","note":null,"summary_classification":null,"items":[],"taxes":[{"rate":22,"base":100,"amount":22,"is_deductible":true,"deductible_percentage":100}],"total":100,"total_with_tax":122,"total_discount":0,"total_paid":0,"total_due":122,"paid_in_full":false,"exchange_rate":null,"attachment_count":0,"has_attachment":false,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-04T08:00:00.000Z"},"description":"Created final summary expense"},"Summary-only":{"value":{"id":"exp_7595a27b5d35015c3ef0c3fe","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":"sup_6595a27b5d35015c3ef0c3fd","type":"invoice","is_draft":false,"voided_at":null,"supplier":{"name":"Orbital Power Systems GmbH","address":"Energieweg 8","address_2":null,"post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","tax_number":"DE987654321","company_number":"HRB 98765","email":"accounts@orbital-power.example","phone":"+493012345678","peppol_id":"0088:9876543210982","is_tax_subject":true},"supplier_document_number":"AP-CUSTOM-001","date":"2025-10-03","date_received":"2025-10-03","date_due":"2025-11-02","date_service":null,"date_service_to":null,"currency_code":"EUR","transaction_type":"domestic","reference":"DE00-2025-001","note":"Supplier provided totals only","summary_classification":"service","items":[],"taxes":[{"rate":19,"base":45.22,"amount":8.59,"is_deductible":true,"deductible_percentage":100,"reverse_charge":false},{"rate":0,"base":125.63,"amount":0,"is_deductible":true,"deductible_percentage":100,"reverse_charge":false}],"total":170.85,"total_with_tax":179.44,"total_discount":0,"total_paid":0,"total_due":179.44,"paid_in_full":false,"exchange_rate":null,"attachment_count":0,"has_attachment":false,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-04T08:00:00.000Z"},"description":"Created summary-only incoming invoice"},"Complete":{"value":{"id":"exp_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":"sup_6595a27b5d35015c3ef0c3fd","type":"invoice","is_draft":false,"voided_at":null,"supplier":{"name":"Orbital Power Systems GmbH","address":"Energieweg 8","address_2":null,"post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","tax_number":"DE987654321","company_number":"HRB 98765","email":"accounts@orbital-power.example","phone":"+493012345678","peppol_id":"0088:9876543210982","is_tax_subject":true},"supplier_document_number":"OPS-2025-001","date":"2025-10-03","date_received":"2025-10-03","date_due":"2025-11-02","date_service":null,"date_service_to":null,"currency_code":"EUR","transaction_type":"domestic","reference":"DE00-2025-001","note":"Ground facility maintenance — March billing period","summary_classification":null,"items":[{"name":"Ground facility maintenance","description":"Monthly ground facility maintenance","quantity":1,"unit":"service","classification":"service","price":100,"gross_price":119,"discounts":[],"taxes":[{"rate":19,"amount":19,"is_deductible":true,"deductible_percentage":100}],"total":100,"total_with_tax":119,"total_tax":19}],"taxes":[{"rate":19,"base":100,"amount":19,"is_deductible":true,"deductible_percentage":100,"reverse_charge":false}],"total":100,"total_with_tax":119,"total_discount":0,"total_paid":0,"total_due":119,"paid_in_full":false,"exchange_rate":null,"attachment_count":1,"has_attachment":true,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-03T08:00:00.000Z"},"description":"Created posted incoming invoice"},"Draft":{"value":{"id":"exp_8595a27b5d35015c3ef0c3ff","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":null,"type":"invoice","is_draft":true,"voided_at":null,"supplier":{"name":"Orbital Power Systems GmbH","address":"Energieweg 8","address_2":null,"post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","tax_number":"DE987654321","company_number":"HRB 98765","email":"accounts@orbital-power.example","phone":"+493012345678","peppol_id":"0088:9876543210982","is_tax_subject":true},"supplier_document_number":null,"date":null,"date_received":null,"date_due":null,"date_service":null,"date_service_to":null,"currency_code":null,"transaction_type":null,"reference":"DE00-2025-001","note":"OCR draft pending review","summary_classification":null,"items":[],"taxes":[],"total":null,"total_with_tax":null,"total_discount":0,"total_paid":0,"total_due":0,"paid_in_full":false,"exchange_rate":null,"attachment_count":0,"has_attachment":false,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-03T08:00:00.000Z"},"description":"Created draft expense"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Duplicate supplier document number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseDuplicateConflictError"},"examples":{"Duplicate supplier document":{"value":{"code":"conflict","message":"An expense for this supplier with the same document number already exists","conflicting_expense_id":"exp_6595a27b5d35015c3ef0c3fd"},"description":"Another active expense for the supplier already uses this supplier document number."}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/report":{"get":{"operationId":"getExpenseCategoryReport","summary":"Get expenses by financial category","description":"Return finalized expense net amounts grouped by financial category. Depending on expense-recognition settings and line overrides, recognized amounts use document dates or generated daily service-period schedules.","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string","format":"date","description":"Report start date in YYYY-MM-DD format. Must be the first calendar day of a month.","example":"2026-01-01"},"required":true,"description":"Report start date in YYYY-MM-DD format. Must be the first calendar day of a month.","name":"date_from","in":"query"},{"schema":{"type":"string","format":"date","description":"Report end date in YYYY-MM-DD format. Must be the final calendar day of a month.","example":"2026-12-31"},"required":true,"description":"Report end date in YYYY-MM-DD format. Must be the final calendar day of a month.","name":"date_to","in":"query"},{"schema":{"type":"string","enum":["recognized","deferred"],"default":"recognized","description":"recognized returns expense recognized inside each period. deferred returns the remaining future expense balance at the end of each period."},"required":false,"description":"recognized returns expense recognized inside each period. deferred returns the remaining future expense balance at the end of each period.","name":"basis","in":"query"},{"schema":{"type":"string","enum":["financial_category"],"default":"financial_category","description":"Report grouping dimension.","example":"financial_category"},"required":false,"description":"Report grouping dimension.","name":"group_by","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Expenses by financial category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseCategoryReportResponse"},"examples":{"Monthly expense categories":{"value":{"basis":"recognized","group_by":"financial_category","calculation_mode":"recognition_entries","periods":[{"period":"2026-01","date_from":"2026-01-01","date_to":"2026-01-31"},{"period":"2026-02","date_from":"2026-02-01","date_to":"2026-02-28"}],"series":[{"key":"fcat_office","financial_category_id":"fcat_office","name":"Office expenses","color":"#2563eb","values":[1200,850],"total":2050},{"key":"uncategorized","financial_category_id":null,"name":"Uncategorized","color":null,"values":[50,125],"total":175}],"totals":[1250,975],"total":2225,"currency_code":"EUR","date_from":"2026-01-01","date_to":"2026-02-28"},"description":"Recognized expense amounts grouped by financial category and month"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/recognition/settings":{"get":{"operationId":"getExpenseRecognitionSettings","summary":"Get expense recognition settings","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Expense recognition settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseRecognitionSettingsResponse"},"example":{"default_method":"service_period_daily"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateExpenseRecognitionSettings","summary":"Update expense recognition settings","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Expense recognition settings","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateExpenseRecognitionSettings"},"examples":{"UseServicePeriodDaily":{"value":{"default_method":"service_period_daily"},"description":"Spread eligible expense lines over their service period by default."},"DisableGeneratedRecognition":{"value":{"default_method":null},"description":"Disable generated schedules and return to immediate expense recognition."}}}}},"responses":{"200":{"description":"Updated expense recognition settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseRecognitionSettingsResponse"},"example":{"default_method":"service_period_daily"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/recognition/backfill":{"post":{"operationId":"backfillExpenseRecognition","summary":"Backfill expense recognition entries","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Expense recognition backfill","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseRecognitionBackfill"},"examples":{"DryRun":{"value":{"date_from":"2026-01-01","date_to":"2026-03-31","dry_run":true,"limit":100},"description":"Preview the eligible expense batch without replacing generated entries."},"GenerateEntries":{"value":{"date_from":"2026-01-01","date_to":"2026-03-31","dry_run":false,"limit":100},"description":"Generate recognition entries for an eligible bounded expense batch."}}}}},"responses":{"200":{"description":"Expense recognition backfill result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseRecognitionBackfillResponse"},"example":{"processed_expenses":12,"generated_entries":36,"dry_run":false,"next_cursor":null}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/recognitions":{"post":{"operationId":"createExpenseRecognition","summary":"Start expense recognition from a document file","description":"Accepts one supplier invoice (PDF, JPEG, PNG, or WebP), creates an invoice-only draft expense with `creation_source=ocr`, and enqueues an async recognition job. For sandbox entities, no provider is called and no usage is charged: the submitted file is not stored and is replaced by a clearly marked deterministic demo invoice; the response exposes `simulation_mode=sandbox_demo`.\n\nReturns **202 Accepted** with the job, expense, and file identifiers. Recognition is asynchronous in live mode; poll `GET /expenses/recognitions/{id}` for status. Terminal success is `ready_for_review` or `needs_attention`; terminal failure is `failed`, with safe `error_code` and `error_message` fields.\n\nPayment suggestions from OCR are advisory only and never mark the expense paid or create payments. Failed provider attempts record zero customer usage. Automatic provider attempts and a permitted customer retry share the same job; billable customer usage is recorded once only after a successful terminal result.\n\n`X-Request-Id` provides account/entity-scoped replay and fails closed with 409 Conflict when reused for different file content.","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Optional idempotency key. Reusing it with the same entity and identical file replays the original result; reusing it with different file content fails with 409 Conflict."},"required":false,"description":"Optional idempotency key. Reusing it with the same entity and identical file replays the original result; reusing it with different file content fails with 409 Conflict.","name":"x-request-id","in":"header"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Supplier invoice PDF or image"}},"required":["file"]}}}},"responses":{"202":{"description":"Recognition job accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseRecognitionCreateResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/recognitions/{id}":{"get":{"operationId":"getExpenseRecognitionById","summary":"Get expense recognition job by ID","description":"Returns recognition job status, extraction results, warnings, reconciliation, and advisory payment suggestion. Entity-scoped.","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string","description":"Expense recognition job ID","example":"erj_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Expense recognition job ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Recognition job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseRecognitionJob"},"examples":{"Queued":{"value":{"id":"erj_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","expense_id":"exp_6595a27b5d35015c3ef0c3fd","file_metadata_id":"fil_6595a27b5d35015c3ef0c3fd","status":"queued","attempts":0,"max_attempts":3,"source_mime_type":"application/pdf","source_bytes":48321,"source_content_sha256":"f5c4c9c33d9b42e4f130cb593f17741b30e0fb23ac95a6d91d01bf438467a17c","simulation_mode":null,"source_replaced":false,"expense_updated_at_snapshot":"2026-07-11T08:00:00.000Z","queued_at":"2026-07-11T08:00:00.000Z","created_at":"2026-07-11T08:00:00.000Z","updated_at":"2026-07-11T08:00:00.000Z"},"description":"Recognition job accepted and waiting for asynchronous processing"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/recognitions/{id}/retry":{"post":{"operationId":"retryExpenseRecognition","summary":"Retry recognition after a transient failure","description":"Re-queues a `failed` recognition job only after an allowed transient provider or source-service error and when attempts remain below `max_attempts`. Bad or unsupported content should be uploaded as a new expense instead.","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string","description":"Expense recognition job ID","example":"erj_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Expense recognition job ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"202":{"description":"Recognition job re-queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseRecognitionJob"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/{id}/recognition":{"get":{"operationId":"getLatestExpenseRecognition","summary":"Get the latest recognition job for an expense","description":"Returns the latest recognition job linked to the expense, or `job: null` for manually created expenses. This makes recognition state durable across navigation.","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Latest recognition job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseRecognitionLookupResponse"},"examples":{"Recognized":{"value":{"job":{"id":"erj_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","expense_id":"exp_6595a27b5d35015c3ef0c3fd","file_metadata_id":"fil_6595a27b5d35015c3ef0c3fd","status":"queued","attempts":0,"max_attempts":3,"source_mime_type":"application/pdf","source_bytes":48321,"source_content_sha256":"f5c4c9c33d9b42e4f130cb593f17741b30e0fb23ac95a6d91d01bf438467a17c","simulation_mode":null,"source_replaced":false,"expense_updated_at_snapshot":"2026-07-11T08:00:00.000Z","queued_at":"2026-07-11T08:00:00.000Z","created_at":"2026-07-11T08:00:00.000Z","updated_at":"2026-07-11T08:00:00.000Z"}},"description":"Latest recognition job linked to the expense"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/{id}":{"get":{"operationId":"getExpenseById","summary":"Get expense by ID","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Expense","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Expense"},"examples":{"200":{"value":{"id":"exp_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":"sup_6595a27b5d35015c3ef0c3fd","type":"invoice","is_draft":false,"voided_at":null,"supplier":{"name":"Orbital Power Systems GmbH","address":"Energieweg 8","address_2":null,"post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","tax_number":"DE987654321","company_number":"HRB 98765","email":"accounts@orbital-power.example","phone":"+493012345678","peppol_id":"0088:9876543210982","is_tax_subject":true},"supplier_document_number":"OPS-2025-001","date":"2025-10-03","date_received":"2025-10-03","date_due":"2025-11-02","date_service":null,"date_service_to":null,"currency_code":"EUR","transaction_type":"domestic","reference":"DE00-2025-001","note":"Ground facility maintenance — March billing period","summary_classification":null,"items":[{"name":"Ground facility maintenance","description":"Monthly ground facility maintenance","quantity":1,"unit":"service","classification":"service","price":100,"gross_price":119,"discounts":[],"taxes":[{"rate":19,"amount":19,"is_deductible":true,"deductible_percentage":100}],"total":100,"total_with_tax":119,"total_tax":19}],"taxes":[{"rate":19,"base":100,"amount":19,"is_deductible":true,"deductible_percentage":100,"reverse_charge":false}],"total":100,"total_with_tax":119,"total_discount":0,"total_paid":0,"total_due":119,"paid_in_full":false,"exchange_rate":null,"attachment_count":1,"has_attachment":true,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-03T08:00:00.000Z"},"description":"Expense"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateExpense","summary":"Update expense","security":[{"Bearer":[]}],"x-codegen-request-body-name":"data","tags":["Expenses"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Expense Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"is_draft":{"type":"boolean"},"supplier_id":{"type":["string","null"]},"supplier":{"anyOf":[{"$ref":"#/components/schemas/ExpenseSupplier"},{"type":"null"}]},"save_supplier":{"type":["boolean","null"],"description":"Whether to save supplier data to the contact directory. When `supplier` is provided, this defaults to true. On update, `save_supplier: true` without a `supplier` object re-applies the expense's stored supplier snapshot to the linked contact."},"supplier_document_number":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"The supplier's own invoice number as printed on their document. Used for duplicate awareness (unique per supplier for active expenses) and accounting exports.","example":"AP-2024-0417"},"date":{"type":["string","null"],"format":"date"},"date_received":{"type":["string","null"],"format":"date"},"date_due":{"type":["string","null"],"format":"date"},"date_service":{"type":["string","null"],"format":"date"},"date_service_to":{"type":["string","null"],"format":"date"},"currency_code":{"type":["string","null"],"minLength":3,"maxLength":3},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export",null]},"reference":{"type":["string","null"],"maxLength":100},"note":{"type":["string","null"],"maxLength":2000},"items":{"type":["array","null"],"items":{"$ref":"#/components/schemas/CreateExpenseItem"},"description":"Optional line items. Provide either `price` (net) or `gross_price` per line (not both); the server computes line totals. Per-line taxes take a rate only, e.g. `taxes: [{ rate: 22 }]`. Omit `items` for a summary-only (quick) expense and send document `total`/`total_with_tax` + `taxes` instead."},"taxes":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ExpenseSummaryTax"}},"total":{"type":["number","null"]},"total_with_tax":{"type":["number","null"]},"total_discount":{"type":["number","null"]},"expected_total_with_tax":{"type":["number","null"],"exclusiveMinimum":0,"description":"Expected total with tax in the currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents. When provided, the system calculates a rounding_correction to reconcile differences between the calculated total and this expected value. Maximum allowed correction is ±1.00 in the same major unit. Useful when importing invoices from external systems with different rounding rules.","example":122},"calculation_mode":{"type":["string","null"],"enum":["b2b_standard","b2c_gross_discount",null],"description":"Optional calculation mode override. When omitted, the entity default is used and falls back to `b2b_standard`.","example":"b2b_standard"},"exchange_rate":{"anyOf":[{"$ref":"#/components/schemas/ExchangeRate"},{"type":"null"}]},"summary_classification":{"anyOf":[{"$ref":"#/components/schemas/ExpenseSummaryClassification"},{"type":"null"}]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"type":{"type":"string","enum":["invoice"]}},"additionalProperties":false},"examples":{"Post draft document":{"value":{"is_draft":false,"supplier_document_number":"OPS-2025-099","date":"2025-10-12","date_received":"2025-10-13","currency_code":"EUR","summary_classification":"service","taxes":[{"rate":22,"base":80,"amount":17.6}],"total":80,"total_with_tax":97.6},"description":"Turn an OCR/manual draft into a posted AP document"},"Update note":{"value":{"note":"Approved by finance"},"description":"Update editable expense metadata without changing lifecycle state"}}}}},"responses":{"200":{"description":"Updated expense","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Expense"},"examples":{"200":{"value":{"id":"exp_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":"sup_6595a27b5d35015c3ef0c3fd","type":"invoice","is_draft":false,"voided_at":null,"supplier":{"name":"Orbital Power Systems GmbH","address":"Energieweg 8","address_2":null,"post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","tax_number":"DE987654321","company_number":"HRB 98765","email":"accounts@orbital-power.example","phone":"+493012345678","peppol_id":"0088:9876543210982","is_tax_subject":true},"supplier_document_number":"OPS-2025-001","date":"2025-10-03","date_received":"2025-10-03","date_due":"2025-11-02","date_service":null,"date_service_to":null,"currency_code":"EUR","transaction_type":"domestic","reference":"DE00-2025-001","note":"Ground facility maintenance — March billing period","summary_classification":null,"items":[{"name":"Ground facility maintenance","description":"Monthly ground facility maintenance","quantity":1,"unit":"service","classification":"service","price":100,"gross_price":119,"discounts":[],"taxes":[{"rate":19,"amount":19,"is_deductible":true,"deductible_percentage":100}],"total":100,"total_with_tax":119,"total_tax":19}],"taxes":[{"rate":19,"base":100,"amount":19,"is_deductible":true,"deductible_percentage":100,"reverse_charge":false}],"total":100,"total_with_tax":119,"total_discount":0,"total_paid":0,"total_due":119,"paid_in_full":false,"exchange_rate":null,"attachment_count":1,"has_attachment":true,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-20T00:00:00.000Z"},"description":"Updated expense"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Duplicate supplier document number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseDuplicateConflictError"},"examples":{"Duplicate supplier document":{"value":{"code":"conflict","message":"An expense for this supplier with the same document number already exists","conflicting_expense_id":"exp_6595a27b5d35015c3ef0c3fd"},"description":"Another active expense for the supplier already uses this supplier document number."}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteExpense","summary":"Delete draft expense","description":"Only draft expenses can be deleted; posted expenses must be voided instead.","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Draft expense deleted"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/{id}/void":{"post":{"operationId":"voidExpense","summary":"Void expense","description":"Voids a posted expense and frees its supplier_document_number for reuse by a new expense from the same supplier. A voided expense can be restored unless that number has since been reused by another active expense from the same supplier.","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Voided expense","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Expense"},"examples":{"200":{"value":{"id":"exp_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":"sup_6595a27b5d35015c3ef0c3fd","type":"invoice","is_draft":false,"voided_at":"2025-10-20T12:00:00.000Z","supplier":{"name":"Orbital Power Systems GmbH","address":"Energieweg 8","address_2":null,"post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","tax_number":"DE987654321","company_number":"HRB 98765","email":"accounts@orbital-power.example","phone":"+493012345678","peppol_id":"0088:9876543210982","is_tax_subject":true},"supplier_document_number":"OPS-2025-001","date":"2025-10-03","date_received":"2025-10-03","date_due":"2025-11-02","date_service":null,"date_service_to":null,"currency_code":"EUR","transaction_type":"domestic","reference":"DE00-2025-001","note":"Ground facility maintenance — March billing period","summary_classification":null,"items":[{"name":"Ground facility maintenance","description":"Monthly ground facility maintenance","quantity":1,"unit":"service","classification":"service","price":100,"gross_price":119,"discounts":[],"taxes":[{"rate":19,"amount":19,"is_deductible":true,"deductible_percentage":100}],"total":100,"total_with_tax":119,"total_tax":19}],"taxes":[{"rate":19,"base":100,"amount":19,"is_deductible":true,"deductible_percentage":100,"reverse_charge":false}],"total":100,"total_with_tax":119,"total_discount":0,"total_paid":0,"total_due":119,"paid_in_full":false,"exchange_rate":null,"attachment_count":1,"has_attachment":true,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-03T08:00:00.000Z"},"description":"Voided expense"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/{id}/restore":{"post":{"operationId":"restoreExpense","summary":"Restore (un-void) an expense","description":"Reverses a void, re-activating the expense. Fails with 409 if its supplier_document_number has since been reused by another active expense from the same supplier.","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Restored expense","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Expense"},"examples":{"200":{"value":{"id":"exp_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","supplier_id":"sup_6595a27b5d35015c3ef0c3fd","type":"invoice","is_draft":false,"voided_at":null,"supplier":{"name":"Orbital Power Systems GmbH","address":"Energieweg 8","address_2":null,"post_code":"10115","city":"Berlin","state":null,"country":"Germany","country_code":"DE","tax_number":"DE987654321","company_number":"HRB 98765","email":"accounts@orbital-power.example","phone":"+493012345678","peppol_id":"0088:9876543210982","is_tax_subject":true},"supplier_document_number":"OPS-2025-001","date":"2025-10-03","date_received":"2025-10-03","date_due":"2025-11-02","date_service":null,"date_service_to":null,"currency_code":"EUR","transaction_type":"domestic","reference":"DE00-2025-001","note":"Ground facility maintenance — March billing period","summary_classification":null,"items":[{"name":"Ground facility maintenance","description":"Monthly ground facility maintenance","quantity":1,"unit":"service","classification":"service","price":100,"gross_price":119,"discounts":[],"taxes":[{"rate":19,"amount":19,"is_deductible":true,"deductible_percentage":100}],"total":100,"total_with_tax":119,"total_tax":19}],"taxes":[{"rate":19,"base":100,"amount":19,"is_deductible":true,"deductible_percentage":100,"reverse_charge":false}],"total":100,"total_with_tax":119,"total_discount":0,"total_paid":0,"total_due":119,"paid_in_full":false,"exchange_rate":null,"attachment_count":1,"has_attachment":true,"metadata":{"source":"manual"},"created_at":"2025-10-03T08:00:00.000Z","updated_at":"2025-10-03T08:00:00.000Z"},"description":"Restored expense"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Duplicate supplier document number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseDuplicateConflictError"},"examples":{"Duplicate supplier document":{"value":{"code":"conflict","message":"An expense for this supplier with the same document number already exists","conflicting_expense_id":"exp_6595a27b5d35015c3ef0c3fd"},"description":"Another active expense for the supplier already uses this supplier document number."}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/{id}/attachments":{"post":{"operationId":"uploadExpenseAttachment","summary":"Upload expense attachment","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"Uploaded attachment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileMetadata"},"examples":{"Uploaded PDF":{"value":{"id":"file_9595a27b5d35015c3ef0c3fa","entity_id":"ent_6595a27b5d35015c3ef0c3fd","invoice_id":null,"estimate_id":null,"credit_note_id":null,"advance_invoice_id":null,"expense_id":"exp_6595a27b5d35015c3ef0c3fd","category":"attachment","url":"https://storage.example.com/si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf","secureUrl":"https://storage.example.com/si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf","publicId":"si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf","secure_url":"https://storage.example.com/si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf","public_id":"si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf","format":"pdf","width":null,"height":null,"bytes":245678,"filename":"supplier-invoice.pdf","mime_type":"application/pdf","metadata":{},"created_at":"2025-10-03T08:05:00.000Z","updated_at":"2025-10-03T08:05:00.000Z"},"description":"Uploaded supplier invoice PDF attached to an expense"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getExpenseAttachments","summary":"List expense attachments","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of expense attachments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FileMetadata"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"file_9595a27b5d35015c3ef0c3fa","entity_id":"ent_6595a27b5d35015c3ef0c3fd","invoice_id":null,"estimate_id":null,"credit_note_id":null,"advance_invoice_id":null,"expense_id":"exp_6595a27b5d35015c3ef0c3fd","category":"attachment","url":"https://storage.example.com/si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf","secureUrl":"https://storage.example.com/si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf","publicId":"si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf","secure_url":"https://storage.example.com/si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf","public_id":"si/entities/ent_6595a27b5d35015c3ef0c3fd/attachments/expense.pdf","format":"pdf","width":null,"height":null,"bytes":245678,"filename":"supplier-invoice.pdf","mime_type":"application/pdf","metadata":{},"created_at":"2025-10-03T08:05:00.000Z","updated_at":"2025-10-03T08:05:00.000Z"}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of expense attachments"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/{id}/attachments/{fileId}":{"delete":{"operationId":"deleteExpenseAttachment","summary":"Delete expense attachment","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"fileId","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Attachment deleted"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Recognition source attachments cannot be deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/expenses/{id}/payments":{"get":{"operationId":"getExpensePayments","summary":"List payments affecting an expense","security":[{"Bearer":[]}],"tags":["Expenses"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of payments affecting the expense","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"pmt_abc123def456","invoice_id":null,"credit_note_id":null,"advance_invoice_id":null,"expense_id":"exp_6595a27b5d35015c3ef0c3fd","applied_to_expense_id":null,"amount":122,"amount_converted":122,"currency_code":"EUR","type":"bank_transfer","date":"2025-10-10T00:00:00.000Z","reference":"DE00-2025-001","tag":null,"note":"Supplier payment","entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"deleted_at":null,"created_at":"2025-10-10T08:00:00.000Z","updated_at":"2025-10-10T08:00:00.000Z"}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Payments affecting the expense"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createExpensePayment","summary":"Create a payment for an expense","security":[{"Bearer":[]}],"x-codegen-request-body-name":"data","tags":["Expenses"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"$ref":"#/components/parameters/RequestId"}],"requestBody":{"description":"Create Expense Payment Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0,"description":"Payment amount in the linked document currency's major unit; for EUR, `29.90` means €29.90, not 2,990 cents.","example":29.9},"type":{"type":"string","enum":["cash","bank_transfer","card","check","paypal","coupon","other","advance"]},"date":{"type":"string","description":"Payment date in YYYY-MM-DD format","example":"2024-01-15"},"tag":{"type":["string","null"],"maxLength":100},"reference":{"type":["string","null"],"maxLength":100},"note":{"type":["string","null"],"maxLength":500},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"required":["amount","type"],"additionalProperties":false},"examples":{"Direct":{"value":{"amount":122,"type":"bank_transfer","date":"2025-10-10","reference":"DE00-2025-001","note":"Supplier payment"},"description":"Direct payment against a supplier invoice expense"}}}}},"responses":{"201":{"description":"Created expense payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"},"examples":{"Direct":{"value":{"id":"pmt_abc123def456","invoice_id":null,"credit_note_id":null,"advance_invoice_id":null,"expense_id":"exp_6595a27b5d35015c3ef0c3fd","applied_to_expense_id":null,"amount":122,"amount_converted":122,"currency_code":"EUR","type":"bank_transfer","date":"2025-10-10T00:00:00.000Z","reference":"DE00-2025-001","tag":null,"note":"Supplier payment","entity_id":"ent_6595a27b5d35015c3ef0c3fd","metadata":{},"deleted_at":null,"created_at":"2025-10-10T08:00:00.000Z","updated_at":"2025-10-10T08:00:00.000Z"},"description":"Created direct payment for the expense"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/email/send":{"post":{"operationId":"sendEmail","summary":"Send email with optional PDF attachment","description":"Send an email with automatic company logo and optional document attachment. When a document_id is provided, a public shareable link is automatically generated and can be included in the email body using the {invoice_link} variable. If the variable is not used, the link is appended to the body. The PDF attachment is opt-in via attach_pdf flag (default: false). Email body supports markdown formatting and template variables like {document_number}, {customer_name}, {entity_name}, {invoice_link}, etc.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Email"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","pattern":"^\\s*[^\\s,@]+@[^\\s,@]+\\.[^\\s,@]+(?:\\s*,\\s*[^\\s,@]+@[^\\s,@]+\\.[^\\s,@]+){0,3}\\s*$","description":"Recipient email address or comma-separated list of up to 4 recipient email addresses","example":"customer@example.com, accounting@example.com"},"subject":{"type":"string","minLength":1,"maxLength":255,"description":"Email subject line. If not provided, uses default from entity settings or a generated subject.","example":"Your Invoice"},"body_text":{"type":"string","minLength":1,"description":"Email body. Supports markdown formatting (**bold**, *italic*, `code`, [links](url), lists, headers). Plain text works fine too! Images and HTML tags are skipped for security. Supports template variables like {document_number}, {customer_name}, {entity_name}, and {invoice_link} for the public invoice URL. If {invoice_link} is not present, a localized markdown link like [View document]({url}) is appended at the bottom.","example":"Please find your invoice attached.\n\n[View document]({invoice_link})"},"document_id":{"type":["string","null"],"description":"ID of the document (invoice, etc.) to reference for sharing. Generates a public shareable link.","example":"inv_123456789"},"attach_pdf":{"type":"boolean","default":false,"description":"Whether to attach the invoice as a PDF. By default, only the public link is included in the email body. Set to true to also attach the PDF file.","example":false},"attach_eslog":{"type":"boolean","default":false,"description":"Whether to attach the document as e-SLOG 2.0 XML (Slovenian electronic invoice format). Only available for Slovenian entities when eslog.validation_status = 'valid'. Can be combined with attach_pdf to attach both formats.","example":false},"sandbox_skip_delivery":{"type":"boolean","default":false,"description":"Sandbox only. Build and validate the full email send flow without actually delivering the email through SES. Useful for testing send behavior after sandbox caps are reached.","example":false},"locale":{"type":["string","null"],"enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS",null],"description":"Override PDF and shareable-link formatting locale. When omitted or null, defaults to the entity's locale. Use this to change date and number formatting per request.","example":"de-DE"},"language":{"anyOf":[{"type":"string","enum":["en","de","sl","it","fr","es","pt","nl","pl","hr","sv","fi","et","bg","cs","sk","nb","is"]},{"type":"string","enum":["en-US","de-DE","it-IT","fr-FR","es-ES","sl-SI","pt-PT","nl-NL","pl-PL","hr-HR","sv-SE","fi-FI","et-EE","bg-BG","cs-CZ","sk-SK","nb-NO","is-IS"]},{"type":"null"}],"description":"Override the PDF and shareable-link label language. Accepts a UI language code like 'de' or a full locale like 'de-DE'. When omitted or null, defaults to the explicit locale or the entity's locale.","example":"de"}},"required":["to"],"additionalProperties":false},"examples":{"Minimal":{"value":{"to":"customer@example.com","document_id":"inv_2024_001"},"description":"Minimal email with document - generates shareable link automatically"},"WithMarkdown":{"value":{"to":"customer@example.com","subject":"Invoice #2024-001","body_text":"# Thank You for Your Business\n\nYour **invoice** is ready for payment.\n\n- **Amount**: $1,234.56\n- **Due Date**: 2024-12-31\n- **Payment Terms**: Net 30\n\n**Access your invoice online**: {invoice_link}\n\n[Contact our billing team](mailto:billing@example.com) if you have questions.\n\nBest regards,\nThe Starward Equipment Team","document_id":"inv_2024_001"},"description":"Email with markdown, {invoice_link} variable, and document"},"WithPdfAttachment":{"value":{"to":"customer@example.com","subject":"Payment Reminder - Invoice 2024-001","body_text":"Dear Customer,\n\nThis is a friendly reminder that your invoice is due for payment. Please review the attached PDF.\n\nYou can also view it online: {invoice_link}\n\nThank you!","document_id":"inv_2024_001","attach_pdf":true},"description":"Email with PDF attachment and shareable link (both included)"},"WithLanguage":{"value":{"to":"kunde@example.de","document_id":"inv_2024_001","attach_pdf":true,"language":"de"},"description":"Email with PDF attachment rendered in German, regardless of entity locale"},"WithLocaleFormatting":{"value":{"to":"customer@example.com","document_id":"inv_2024_001","attach_pdf":true,"locale":"de-DE"},"description":"Email with PDF/link formatting overridden to German date and number formats."},"WithEslogAttachment":{"value":{"to":"buyer@example.si","document_id":"inv_2024_001","attach_pdf":true,"attach_eslog":true},"description":"Send both PDF and e-SLOG XML for a Slovenian document that already has valid e-SLOG validation."},"SandboxDryRun":{"value":{"to":"customer@example.com","document_id":"inv_2024_001","attach_pdf":true,"sandbox_skip_delivery":true},"description":"Sandbox-only dry run that builds and validates the email without sending real email."},"Complete":{"value":{"to":"accounting@customer.com","subject":"Invoice #INV-2024-001234 - $5,678.90 Due","body_text":"# Invoice Payment Notice\n\nDear Valued Customer,\n\nWe appreciate your business! Your invoice is ready for review and payment.\n\n## Invoice Details\n\n- **Invoice Number**: INV-2024-001234\n- **Invoice Date**: 2024-11-15\n- **Total Amount**: **$5,678.90**\n- **Amount Due**: **$5,678.90**\n- **Due Date**: **2024-12-15**\n- **Payment Terms**: Net 30\n\n## What's Included\n\n- Mission planning services (120 hours)\n- Ground segment implementation and support\n- Documentation and training materials\n\n## Access Your Invoice\n\nView the complete invoice here: {invoice_link}\n\n## Next Steps\n\n1. Review your invoice\n2. Process payment through your preferred method\n3. Contact us with any questions\n\n## Payment Methods\n\n- Bank Transfer: [banking details]\n- Credit Card: [payment link](https://pay.example.com)\n- Check: Mail to Horizon Launch Systems Inc., 100 Rocket Row, Houston, TX 77058\n\nFor questions or assistance, please [contact our billing team](mailto:billing@example.com) or call +1-555-123-4567.\n\nThank you for your business!\n\nBest regards,\n**Horizon Launch Systems Finance Team**","document_id":"inv_2024_001234","attach_pdf":false},"description":"Complete professional invoice email with {invoice_link} and no PDF attachment"}}}}},"responses":{"200":{"description":"Email sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string","description":"AWS SES message ID for tracking","example":"0000014d-3f45-4d2b-b470-0c8b9d1a4d6b@us-east-1.amazonses.com"},"status":{"type":"string","enum":["sent","queued","skipped"],"description":"Email send status","example":"sent"},"to":{"type":"string","description":"Recipient email address or comma-separated list of up to 4 recipient email addresses","example":"customer@example.com, accounting@example.com"},"subject":{"type":"string","description":"Email subject","example":"Your Invoice"},"shareable_link":{"type":"string","format":"uri","description":"Public URL for viewing the invoice online (if document_id was provided)","example":"http://localhost:3001/documents/shareable/inv_share_abc123..."},"sandbox_skip_delivery":{"type":"boolean","description":"True when sandbox testing used the send flow without delivering the email.","example":true}},"required":["message_id","status","to","subject"]},"examples":{"Minimal":{"value":{"message_id":"0000014d-3f45-4d2b-b470-0c8b9d1a4d6b@us-east-1.amazonses.com","status":"sent","to":"customer@example.com","subject":"Invoice from Starward Equipment Co.","shareable_link":"http://localhost:3001/documents/shareable/inv_share_abc123..."},"description":"Email sent with auto-generated shareable link"},"WithMarkdown":{"value":{"message_id":"0000014e-4f56-5e3c-c581-1d9c2e5b7e8c@us-east-1.amazonses.com","status":"sent","to":"customer@example.com","subject":"Invoice #2024-001","shareable_link":"http://localhost:3001/documents/shareable/inv_share_def456..."},"description":"Email sent with {invoice_link} replaced with shareable URL"},"WithPdfAttachment":{"value":{"message_id":"0000014f-5f67-6f4d-d692-2e0d3f6c8f9d@us-east-1.amazonses.com","status":"sent","to":"customer@example.com","subject":"Payment Reminder - Invoice 2024-001","shareable_link":"http://localhost:3001/documents/shareable/inv_share_ghi789..."},"description":"Email sent with both PDF attachment and shareable link"},"Complete":{"value":{"message_id":"00000150-6f78-7f5e-e7a3-3f1e4g7d9a0e@us-east-1.amazonses.com","status":"sent","to":"accounting@customer.com","subject":"Invoice #INV-2024-001234 - $5,678.90 Due","shareable_link":"http://localhost:3001/documents/shareable/inv_share_jkl012..."},"description":"Professional invoice email sent with {invoice_link} variable processed"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/share":{"post":{"operationId":"shareDocument","summary":"Make document shareable","description":"Generate a shareable token for a document. Document type is automatically detected from the ID prefix (inv_, est_, cre_, adv_). If the document is already shared, returns the existing token. Can be used to re-share a document that was previously unshared.","security":[{"Bearer":[]}],"tags":["Documents","Invoices","Estimates","CreditNotes","Advance Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Shareable Link Generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareableId"},"example":{"shareable_id":"inv_share_abc123def456xyz"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getShareableId","summary":"Get shareable token","description":"Retrieve the shareable token for a document if one exists. Document type is automatically detected from the ID prefix (inv_, est_, cre_, adv_).","security":[{"Bearer":[]}],"tags":["Documents","Invoices","Estimates","CreditNotes","Advance Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Shareable Token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareableId"},"example":{"shareable_id":"inv_share_abc123def456xyz"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unshareDocument","summary":"Unshare document","description":"Remove the shareable token from a document. The document will no longer be accessible via public link. Document type is automatically detected from the ID prefix (inv_, est_, cre_, adv_).","security":[{"Bearer":[]}],"tags":["Documents","Invoices","Estimates","CreditNotes","Advance Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Document unshared successfully"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"post":{"operationId":"createWebhook","summary":"Create a new webhook","description":"Create a webhook endpoint. The response includes the full secret which is only visible on creation and when rotated.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Webhooks"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Create Webhook Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri","description":"The HTTPS URL to send webhook events to. Cannot target localhost, private IPs, or internal domains.","example":"https://example.com/webhooks"},"description":{"type":"string","maxLength":500,"description":"Optional description for this webhook","example":"Production webhook"},"events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.updated","invoice.sent","invoice.paid","invoice.overdue","invoice.cancelled","invoice.deleted","invoice.restored","invoice.voided","invoice.finalized","customer.created","customer.updated","customer.deleted","customer.restored","customer.permanently_deleted","payment.received","payment.failed","payment.deleted","payment.restored","payment.permanently_deleted","estimate.created","estimate.sent","estimate.accepted","estimate.rejected","estimate.deleted","estimate.restored","credit_note.created","credit_note.issued","credit_note.voided","credit_note.deleted","credit_note.restored","advance_invoice.created","advance_invoice.paid","advance_invoice.applied","advance_invoice.voided","advance_invoice.deleted","advance_invoice.restored","item.created","item.updated","item.deleted","item.restored","item.permanently_deleted","tax.created","tax.updated","tax.deleted","tax.restored","tax.permanently_deleted","recurring_invoice.created","recurring_invoice.updated","recurring_invoice.deleted","recurring_invoice.restored","recurring_invoice.permanently_deleted","recurring_invoice.paused","recurring_invoice.resumed","recurring_invoice.invoice_generated","recurring_invoice.generation_failed","recurring_invoice.completed","stripe_app.connected","stripe_app.disconnected","stripe_app.settings_updated","order.created","order.updated","order.deleted","order.restored","order.permanently_deleted","order.processed","order.cancelled","order.failed","order_integration.created","order_integration.updated","order_integration.deleted","delivery_note.created","delivery_note.sent","delivery_note.cancelled","delivery_note.voided","delivery_note.deleted","delivery_note.restored","expense.created","expense.updated","expense.finalized","expense.voided","expense.deleted","e_invoicing.submission.created","e_invoicing.submission.delivered","e_invoicing.submission.failed","e_invoicing.enrollment.verified","e_invoicing.enrollment.rejected","e_invoicing.supplier.onboarded","e_invoicing.supplier.rejected"]},"minItems":1,"description":"Events that trigger this webhook","example":["invoice.created","invoice.paid"]},"active":{"type":"boolean","default":true,"description":"Whether webhook is active","example":true},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"required":["url","events"],"additionalProperties":false},"examples":{"Minimal":{"value":{"url":"https://example.com/webhooks","events":["invoice.created"]},"description":"Minimal webhook with only required fields"},"Payments only":{"value":{"url":"https://example.com/webhooks/payments","events":["payment.received","invoice.paid"]},"description":"Webhook focused on payment reconciliation events."},"Recurring invoice lifecycle":{"value":{"url":"https://example.com/webhooks/recurring-invoices","events":["recurring_invoice.paused","recurring_invoice.resumed","recurring_invoice.generation_failed"],"active":true},"description":"Webhook for recurring invoice schedule changes and failures."},"Complete":{"value":{"url":"https://example.com/webhooks","description":"Production webhook for invoice events","events":["invoice.created","invoice.updated","invoice.paid","invoice.cancelled"],"active":true,"metadata":{"environment":"production"}},"description":"Complete webhook with all optional fields"}}}}},"responses":{"201":{"description":"Created webhook with secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookWithSecret"},"examples":{"Created":{"value":{"id":"whk_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","url":"https://example.com/webhooks","description":null,"secret":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2","events":["invoice.created","invoice.paid"],"active":true,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"},"description":"Created webhook (secret visible only on creation)"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getWebhooks","summary":"List all webhooks","description":"Retrieve a paginated list of webhooks for the entity. Secrets are masked in the response.","security":[{"Bearer":[]}],"tags":["Webhooks"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"whk_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","url":"https://example.com/webhooks","description":null,"secret":"whsec_****...****","events":["invoice.created","invoice.paid"],"active":true,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of webhooks"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"get":{"operationId":"getWebhookById","summary":"Get a webhook by ID","description":"Retrieve a single webhook. The secret is masked in the response.","security":[{"Bearer":[]}],"tags":["Webhooks"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Webhook details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"},"examples":{"Webhook":{"value":{"id":"whk_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","url":"https://example.com/webhooks","description":null,"secret":"whsec_****...****","events":["invoice.created","invoice.paid"],"active":true,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"},"description":"Webhook details (secret is masked)"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateWebhook","summary":"Update a webhook","description":"Update webhook URL, events, active status, or description.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Webhooks"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Webhook Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri","description":"The HTTPS URL to send webhook events to. Cannot target localhost, private IPs, or internal domains.","example":"https://example.com/webhooks"},"description":{"type":["string","null"],"maxLength":500},"events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.updated","invoice.sent","invoice.paid","invoice.overdue","invoice.cancelled","invoice.deleted","invoice.restored","invoice.voided","invoice.finalized","customer.created","customer.updated","customer.deleted","customer.restored","customer.permanently_deleted","payment.received","payment.failed","payment.deleted","payment.restored","payment.permanently_deleted","estimate.created","estimate.sent","estimate.accepted","estimate.rejected","estimate.deleted","estimate.restored","credit_note.created","credit_note.issued","credit_note.voided","credit_note.deleted","credit_note.restored","advance_invoice.created","advance_invoice.paid","advance_invoice.applied","advance_invoice.voided","advance_invoice.deleted","advance_invoice.restored","item.created","item.updated","item.deleted","item.restored","item.permanently_deleted","tax.created","tax.updated","tax.deleted","tax.restored","tax.permanently_deleted","recurring_invoice.created","recurring_invoice.updated","recurring_invoice.deleted","recurring_invoice.restored","recurring_invoice.permanently_deleted","recurring_invoice.paused","recurring_invoice.resumed","recurring_invoice.invoice_generated","recurring_invoice.generation_failed","recurring_invoice.completed","stripe_app.connected","stripe_app.disconnected","stripe_app.settings_updated","order.created","order.updated","order.deleted","order.restored","order.permanently_deleted","order.processed","order.cancelled","order.failed","order_integration.created","order_integration.updated","order_integration.deleted","delivery_note.created","delivery_note.sent","delivery_note.cancelled","delivery_note.voided","delivery_note.deleted","delivery_note.restored","expense.created","expense.updated","expense.finalized","expense.voided","expense.deleted","e_invoicing.submission.created","e_invoicing.submission.delivered","e_invoicing.submission.failed","e_invoicing.enrollment.verified","e_invoicing.enrollment.rejected","e_invoicing.supplier.onboarded","e_invoicing.supplier.rejected"]},"minItems":1},"active":{"type":"boolean"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"additionalProperties":false},"examples":{"UpdateUrl":{"value":{"url":"https://new-url.example.com/webhooks"},"description":"Update webhook URL"},"UpdateEvents":{"value":{"events":["invoice.created","customer.created","payment.received"]},"description":"Update subscribed events"},"Disable":{"value":{"active":false},"description":"Temporarily disable deliveries without deleting the webhook or rotating its secret."}}}}},"responses":{"200":{"description":"Updated webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"},"examples":{"Updated":{"value":{"id":"whk_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","url":"https://example.com/webhooks","description":null,"secret":"whsec_****...****","events":["invoice.created","invoice.paid"],"active":true,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"},"description":"Updated webhook"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook","description":"Permanently delete a webhook endpoint. Pending deliveries will be cancelled.","security":[{"Bearer":[]}],"tags":["Webhooks"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Webhook deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"examples":{"Deleted":{"value":{"success":true},"description":"Webhook successfully deleted"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/test":{"post":{"operationId":"testWebhook","summary":"Test a webhook","description":"Send a test event to the webhook endpoint to verify connectivity.","security":[{"Bearer":[]}],"tags":["Webhooks"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Test delivery result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"},"examples":{"Success":{"value":{"id":"whd_6595a27b5d35015c3ef0c3fd","webhook_id":"whk_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","event_type":"webhook.test","status":"success","request_body":{"event":"webhook.test","data":{}},"response_status":200,"response_body":"OK","error_message":null,"attempt":1,"max_attempts":1,"next_retry_at":null,"duration_ms":150,"created_at":"2024-01-01T00:00:00.000Z","completed_at":"2024-01-01T00:00:00.150Z"},"description":"Successful test delivery"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/deliveries":{"get":{"operationId":"getWebhookDeliveries","summary":"List webhook deliveries","description":"Retrieve a paginated list of delivery attempts for a specific webhook.","security":[{"Bearer":[]}],"tags":["Webhooks"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"whd_6595a27b5d35015c3ef0c3fd","webhook_id":"whk_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","event_type":"invoice.created","status":"success","request_body":{"event":"invoice.created","data":{"id":"inv_123"}},"response_status":200,"response_body":"OK","error_message":null,"attempt":1,"max_attempts":5,"next_retry_at":null,"duration_ms":120,"created_at":"2024-01-01T00:00:00.000Z","completed_at":"2024-01-01T00:00:00.120Z"}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of webhook deliveries"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/rotate-secret":{"post":{"operationId":"rotateWebhookSecret","summary":"Rotate webhook secret","description":"Generate a new signing secret for the webhook. The previous secret is immediately invalidated.","security":[{"Bearer":[]}],"tags":["Webhooks"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Webhook with new secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookWithSecret"},"examples":{"Rotated":{"value":{"id":"whk_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","url":"https://example.com/webhooks","description":null,"secret":"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2","events":["invoice.created","invoice.paid"],"active":true,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"},"description":"Webhook with new secret (previous secret invalidated)"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account-webhooks":{"post":{"operationId":"createAccountWebhook","summary":"Create a new account webhook","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Account Webhooks"],"parameters":[{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"requestBody":{"description":"Create Account Webhook Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri","description":"The HTTPS URL to send account-scoped webhook events to.","example":"https://example.com/account-webhooks"},"description":{"type":["string","null"],"maxLength":500,"description":"Optional description for this webhook","example":"Apollo white-label billing events"},"events":{"type":"array","items":{"type":"string","enum":["white_label_subscription.subscribed","white_label_subscription.upgraded","white_label_subscription.downgrade_scheduled","white_label_subscription.downgraded","white_label_subscription.cancellation_scheduled","white_label_subscription.cancelled","white_label_subscription.renewed","white_label_subscription.expired","white_label_subscription.payment_failed"]},"minItems":1,"description":"Events that trigger this account webhook","example":["white_label_subscription.subscribed","white_label_subscription.cancelled"]},"active":{"type":"boolean","default":true,"description":"Whether webhook is active","example":true},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"required":["url","events"],"additionalProperties":false},"examples":{"Minimal":{"value":{"url":"https://example.com/account-webhooks","events":["white_label_subscription.subscribed"]}},"Subscription billing lifecycle":{"value":{"url":"https://example.com/account-webhooks/billing","description":"White-label subscription billing events","events":["white_label_subscription.subscribed","white_label_subscription.renewed","white_label_subscription.cancelled"],"active":true}}}}}},"responses":{"201":{"description":"Created account webhook with secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountWebhookWithSecret"},"examples":{"Created":{"value":{"id":"accwh_6595a27b5d35015c3ef0c3fd","account_id":"acc_6595a27b5d35015c3ef0c3fd","url":"https://example.com/account-webhooks","description":"Apollo billing lifecycle","secret":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","events":["white_label_subscription.subscribed","white_label_subscription.cancelled"],"active":true,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getAccountWebhooks","summary":"List all account webhooks","security":[{"Bearer":[]}],"tags":["Account Webhooks"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"List of account webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountWebhookResponse"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"accwh_6595a27b5d35015c3ef0c3fd","account_id":"acc_6595a27b5d35015c3ef0c3fd","url":"https://example.com/account-webhooks","description":"Apollo billing lifecycle","secret":"whsec_****...****","events":["white_label_subscription.subscribed","white_label_subscription.cancelled"],"active":true,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of account webhooks"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account-webhooks/{id}":{"get":{"operationId":"getAccountWebhookById","summary":"Get an account webhook by ID","security":[{"Bearer":[]}],"tags":["Account Webhooks"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"Account webhook details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountWebhookResponse"},"examples":{"Webhook":{"value":{"id":"accwh_6595a27b5d35015c3ef0c3fd","account_id":"acc_6595a27b5d35015c3ef0c3fd","url":"https://example.com/account-webhooks","description":"Apollo billing lifecycle","secret":"whsec_****...****","events":["white_label_subscription.subscribed","white_label_subscription.cancelled"],"active":true,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateAccountWebhook","summary":"Update an account webhook","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Account Webhooks"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"requestBody":{"description":"Update Account Webhook Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri","description":"The HTTPS URL to send account-scoped webhook events to.","example":"https://example.com/account-webhooks"},"description":{"type":["string","null"],"maxLength":500},"events":{"type":"array","items":{"type":"string","enum":["white_label_subscription.subscribed","white_label_subscription.upgraded","white_label_subscription.downgrade_scheduled","white_label_subscription.downgraded","white_label_subscription.cancellation_scheduled","white_label_subscription.cancelled","white_label_subscription.renewed","white_label_subscription.expired","white_label_subscription.payment_failed"]},"minItems":1},"active":{"type":"boolean"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"additionalProperties":false},"examples":{"UpdateEvents":{"value":{"events":["white_label_subscription.subscribed","white_label_subscription.renewed"]}},"Disable":{"value":{"active":false}}}}}},"responses":{"200":{"description":"Updated account webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountWebhookResponse"},"examples":{"Updated":{"value":{"id":"accwh_6595a27b5d35015c3ef0c3fd","account_id":"acc_6595a27b5d35015c3ef0c3fd","url":"https://example.com/account-webhooks","description":"Apollo billing lifecycle","secret":"whsec_****...****","events":["white_label_subscription.subscribed","white_label_subscription.cancelled"],"active":true,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteAccountWebhook","summary":"Delete an account webhook","security":[{"Bearer":[]}],"tags":["Account Webhooks"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"Account webhook deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]},"examples":{"Deleted":{"value":{"success":true}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account-webhooks/{id}/test":{"post":{"operationId":"testAccountWebhook","summary":"Test an account webhook","security":[{"Bearer":[]}],"tags":["Account Webhooks"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"Test delivery result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountWebhookDelivery"},"examples":{"Success":{"value":{"id":"accwhd_6595a27b5d35015c3ef0c3fd","account_webhook_id":"accwh_6595a27b5d35015c3ef0c3fd","account_id":"acc_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","event_type":"account_webhook.test","status":"success","request_body":{"event":"white_label_subscription.subscribed","data":{"account_id":"acc_6595a27b5d35015c3ef0c3fd"},"timestamp":"2024-01-01T00:00:00.000Z"},"response_status":200,"response_body":"OK","error_message":null,"attempt":1,"max_attempts":5,"next_retry_at":null,"duration_ms":120,"created_at":"2024-01-01T00:00:00.000Z","completed_at":"2024-01-01T00:00:00.120Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account-webhooks/{id}/deliveries":{"get":{"operationId":"getAccountWebhookDeliveries","summary":"List account webhook deliveries","security":[{"Bearer":[]}],"tags":["Account Webhooks"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"List of deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountWebhookDelivery"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"accwhd_6595a27b5d35015c3ef0c3fd","account_webhook_id":"accwh_6595a27b5d35015c3ef0c3fd","account_id":"acc_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","event_type":"white_label_subscription.subscribed","status":"success","request_body":{"event":"white_label_subscription.subscribed","data":{"account_id":"acc_6595a27b5d35015c3ef0c3fd"},"timestamp":"2024-01-01T00:00:00.000Z"},"response_status":200,"response_body":"OK","error_message":null,"attempt":1,"max_attempts":5,"next_retry_at":null,"duration_ms":120,"created_at":"2024-01-01T00:00:00.000Z","completed_at":"2024-01-01T00:00:00.120Z"}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of account webhook deliveries"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account-webhooks/{id}/rotate-secret":{"post":{"operationId":"rotateAccountWebhookSecret","summary":"Rotate account webhook secret","security":[{"Bearer":[]}],"tags":["Account Webhooks"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"Account webhook with new secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountWebhookWithSecret"},"examples":{"Rotated":{"value":{"id":"accwh_6595a27b5d35015c3ef0c3fd","account_id":"acc_6595a27b5d35015c3ef0c3fd","url":"https://example.com/account-webhooks","description":"Apollo billing lifecycle","secret":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","events":["white_label_subscription.subscribed","white_label_subscription.cancelled"],"active":true,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/furs/settings":{"get":{"operationId":"getFursSettings","summary":"Get FURS settings","description":"Retrieve FURS fiscalization settings for the entity, including certificate status and configuration","security":[{"Bearer":[]}],"tags":["FURS Settings"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"FURS Settings","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether FURS fiscalization is enabled"},"default_skip_fiscalization":{"type":"boolean","description":"Whether new FURS-capable documents skip fiscalization by default"},"numbering_strategy":{"type":"string","enum":["B","C"],"description":"Numbering strategy"},"operator_tax_number":{"type":"string","description":"Operator tax number"},"operator_label":{"type":"string","description":"Operator label"},"certificate_expiry":{"type":"string","format":"date-time","description":"Certificate expiration date"},"has_certificate":{"type":"boolean","description":"Whether a certificate is uploaded"},"certificate_status":{"type":"string","enum":["valid","expiring_soon","expired","missing"],"description":"Certificate status"}},"required":["enabled","default_skip_fiscalization","has_certificate"]},"examples":{"Configured Settings":{"value":{"enabled":true,"numbering_strategy":"C","operator_tax_number":"12345678","operator_label":"Alex Carter","certificate_expiry":"2025-12-31T23:59:59.000Z","certificate_status":"valid","has_certificate":true},"description":"FURS settings with valid certificate"},"Missing Certificate":{"value":{"enabled":true,"numbering_strategy":"C","operator_tax_number":"12345678","operator_label":"Alex Carter","certificate_expiry":null,"certificate_status":"missing","has_certificate":false},"description":"FURS settings without certificate"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updateFursSettings","summary":"Update FURS settings","description":"Update FURS fiscalization settings for the entity. Certificate must be uploaded separately via POST /fiscalization/furs/settings/certificate","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["FURS Settings"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update FURS Settings Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Enable/disable FURS fiscalization","example":true},"default_skip_fiscalization":{"type":"boolean","description":"When true, new FURS-capable documents start with fiscalization skipped by default. Payment type still controls the final state and non-bank-transfer payments force fiscalization back on.","example":false},"numbering_strategy":{"type":"string","enum":["B","C"],"description":"Numbering strategy: B (device-level) or C (centralized)","example":"C"},"operator_tax_number":{"type":"string","description":"Operator tax number for API key usage","example":"12345678"},"operator_label":{"type":"string","description":"Operator label/name","example":"Cash Register 1"}},"additionalProperties":false},"examples":{"Enable FURS":{"value":{"enabled":true,"numbering_strategy":"C","operator_tax_number":"12345678","operator_label":"Alex Carter"},"description":"Enable FURS with centralized numbering strategy"},"Update Strategy":{"value":{"numbering_strategy":"B"},"description":"Change to device-level numbering strategy"},"Update default operator":{"value":{"operator_tax_number":"87654321","operator_label":"Evening shift"},"description":"Set the entity-level default FURS operator used by API-key based invoice creation."},"Disable FURS":{"value":{"enabled":false},"description":"Disable FURS fiscalization for an entity that no longer needs Slovenian fiscalization."}}}}},"responses":{"200":{"description":"FURS Settings Updated","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether FURS fiscalization is enabled"},"default_skip_fiscalization":{"type":"boolean","description":"Whether new FURS-capable documents skip fiscalization by default"},"numbering_strategy":{"type":"string","enum":["B","C"],"description":"Numbering strategy"},"operator_tax_number":{"type":"string","description":"Operator tax number"},"operator_label":{"type":"string","description":"Operator label"},"certificate_expiry":{"type":"string","format":"date-time","description":"Certificate expiration date"},"has_certificate":{"type":"boolean","description":"Whether a certificate is uploaded"},"certificate_status":{"type":"string","enum":["valid","expiring_soon","expired","missing"],"description":"Certificate status"}},"required":["enabled","default_skip_fiscalization","has_certificate"]},"examples":{"Configured Settings":{"value":{"enabled":true,"numbering_strategy":"C","operator_tax_number":"12345678","operator_label":"Alex Carter","certificate_expiry":"2025-12-31T23:59:59.000Z","certificate_status":"valid","has_certificate":true},"description":"FURS settings with valid certificate"},"Missing Certificate":{"value":{"enabled":true,"numbering_strategy":"C","operator_tax_number":"12345678","operator_label":"Alex Carter","certificate_expiry":null,"certificate_status":"missing","has_certificate":false},"description":"FURS settings without certificate"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/furs/internal-act/report.pdf":{"get":{"operationId":"generateFursInternalActPdf","summary":"Download FURS internal act PDF","description":"Generate the Slovenian FURS internal act as a PDF attachment based on the entity's active premises, devices, and numbering strategy.","security":[{"Bearer":[]}],"tags":["FURS Internal Act"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"FURS internal act PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/furs/internal-act/report.docx":{"get":{"operationId":"generateFursInternalActDocx","summary":"Download FURS internal act DOCX","description":"Generate the Slovenian FURS internal act as an editable DOCX attachment based on the entity's active premises, devices, and numbering strategy.","security":[{"Bearer":[]}],"tags":["FURS Internal Act"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"FURS internal act DOCX","content":{"application/vnd.openxmlformats-officedocument.wordprocessingml.document":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/furs/settings/certificate":{"post":{"operationId":"uploadFursCertificate","summary":"Upload FURS certificate","description":"Upload a P12/PFX certificate for FURS fiscalization. The certificate will be processed to extract expiry date and stored securely. The passphrase will be encrypted before storage. Certificate is entity-specific and required for fiscalizing invoices.","security":[{"Bearer":[]}],"tags":["FURS Certificate"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"P12/PFX certificate file","format":"binary"},"passphrase":{"type":"string","description":"Certificate passphrase (will be encrypted before storage)","example":"my-secure-passphrase"}}}}}},"responses":{"200":{"description":"Certificate Uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"certificate_expiry":{"type":"string","format":"date-time","description":"Certificate expiration date (ISO 8601 format)","example":"2025-12-31T00:00:00Z"},"message":{"type":"string","description":"Success message","example":"Certificate uploaded and processed successfully"}},"required":["certificate_expiry","message"]},"examples":{"Success":{"value":{"certificate_expiry":"2025-12-31T23:59:59.000Z","certificate_cn":"12345678","certificate_issuer":"SIGOV-CA2","uploaded_at":"2025-01-15T10:30:00.000Z","message":"Certificate uploaded and validated successfully"},"description":"Successfully uploaded FURS certificate"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getFursCertificate","summary":"Get certificate metadata","description":"Retrieve certificate metadata including expiry date and upload time. Does not return the certificate or private key.","security":[{"Bearer":[]}],"tags":["FURS Certificate"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"FURS Certificate Metadata","content":{"application/json":{"schema":{"type":"object","properties":{"certificate_expiry":{"type":"string"},"certificate_cn":{"type":["string","null"]},"certificate_issuer":{"type":["string","null"]},"uploaded_at":{"type":"string"},"message":{"type":"string"}},"required":["certificate_expiry","certificate_cn","certificate_issuer","uploaded_at","message"]},"examples":{"Success":{"value":{"certificate_expiry":"2025-12-31T23:59:59.000Z","certificate_cn":"12345678","certificate_issuer":"SIGOV-CA2","uploaded_at":"2025-01-15T10:30:00.000Z","message":"Certificate uploaded and validated successfully"},"description":"Successfully uploaded FURS certificate"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteFursCertificate","summary":"Delete FURS certificate","description":"Delete the FURS certificate for the entity. This will remove both the uploaded file reference and the extracted certificate from the database.","security":[{"Bearer":[]}],"tags":["FURS Certificate"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Certificate deleted successfully"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/furs/premises":{"get":{"operationId":"listFursBusinessPremises","summary":"List all business premises","description":"Retrieve all registered business premises for the entity. Each premise represents a physical location or movable unit where invoices are issued.","tags":["FURS Premises"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Business Premises List","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FursBusinessPremise"}},"examples":{"Business Premises":{"value":[]}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/furs/premises/{id}":{"get":{"operationId":"getFursBusinessPremise","summary":"Get a business premise","description":"Retrieve details of a specific business premise by ID, including its electronic devices.","tags":["FURS Premises"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","description":"Business premise ID","example":"premise_507f1f77bcf86cd799439011"},"required":true,"description":"Business premise ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Business Premise Details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FursBusinessPremise"},"examples":{"Business Premise":{"value":{"id":"premise_507f1f77bcf86cd799439011","business_premise_name":"Main Office","entity_id":"ent_507f1f77bcf86cd799439011","real_estate":{"cadastral_number":"1234","building_number":"5","building_section":"1","street":"Dunajska cesta","house_number":"22","house_number_additional":"A","community":"Ljubljana","city":"Ljubljana","postal_code":"1000"},"movable_premise":null,"created_at":"2025-01-01T00:00:00.000Z","updated_at":"2025-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateFursBusinessPremise","summary":"Update a business premise","description":"Update mutable FURS business premise settings. The starting number can only be changed before invoices have been issued for the premise-level sequence.","tags":["FURS Premises"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","description":"Business premise ID","example":"premise_507f1f77bcf86cd799439011"},"required":true,"description":"Business premise ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update FURS Business Premise Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"starting_number":{"type":["integer","null"],"minimum":1,"maximum":999999999,"description":"Optional first fiscal invoice number for this premise/device sequence. Can only be changed before invoices have been issued for the matching fiscal sequence.","example":100}},"additionalProperties":false},"examples":{"Set starting number":{"value":{"starting_number":250},"description":"Set the next premise-level invoice number before any invoices have used this sequence."},"Clear starting number":{"value":{"starting_number":null},"description":"Clear the configured premise-level starting number."}}}}},"responses":{"200":{"description":"Updated Business Premise","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FursBusinessPremise"},"examples":{"Updated Business Premise":{"value":{"id":"premise_507f1f77bcf86cd799439011","entity_id":"ent_507f1f77bcf86cd799439011","business_premise_name":"STORE1","type":"real_estate","real_estate":null,"movable_premise":null,"is_active":true,"starting_number":250,"registered_at":"2025-01-01T00:00:00.000Z","closed_at":null,"created_at":"2025-01-01T00:00:00.000Z","updated_at":"2025-01-02T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/furs/premises/real-estate":{"post":{"operationId":"registerFursRealEstatePremise","summary":"Register real estate premise","description":"Register a real estate (physical location) business premise with FURS (Slovenia). Required before fiscalizing invoices from this location.","tags":["FURS Premises"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Register Real Estate Premise Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"business_premise_name":{"type":"string","minLength":1,"maxLength":20,"description":"Business premise name/identifier (e.g., 'P1', 'TRGOVINA1')","example":"P1"},"real_estate":{"type":"object","properties":{"cadastral_number":{"type":"string","minLength":1,"pattern":"^\\d+$","description":"Cadastral number of the property (required, numeric, max 9999)","example":"123"},"building_number":{"type":"string","minLength":1,"pattern":"^\\d+$","description":"Building number (required, numeric, max 99999)","example":"456"},"building_section":{"type":"string","minLength":1,"pattern":"^\\d+$","description":"Building section number (required, numeric, max 9999)","example":"1"},"street":{"type":"string","minLength":1,"maxLength":100,"description":"Street name (required, max 100 chars)","example":"Dunajska cesta"},"house_number":{"type":"string","minLength":1,"maxLength":10,"description":"House number (required, max 10 chars)","example":"22"},"house_number_additional":{"type":["string","null"],"maxLength":10,"description":"Additional house number suffix (optional, max 10 chars)","example":"A"},"community":{"type":"string","minLength":1,"maxLength":100,"description":"Community / občina name (required, max 100 chars)","example":"Ljubljana"},"city":{"type":"string","minLength":1,"maxLength":100,"description":"City name (required, max 100 chars)","example":"Ljubljana"},"postal_code":{"type":"string","minLength":4,"maxLength":4,"pattern":"^\\d{4}$","description":"Postal code (required, exactly 4 digits)","example":"1000"}},"required":["cadastral_number","building_number","building_section","street","house_number","community","city","postal_code"],"description":"Real estate (physical location) details"},"starting_number":{"type":["integer","null"],"minimum":1,"maximum":999999999,"description":"Optional first fiscal invoice number for this premise/device sequence. Can only be changed before invoices have been issued for the matching fiscal sequence.","example":100}},"required":["business_premise_name","real_estate"],"additionalProperties":false},"examples":{"Physical Store":{"value":{"business_premise_name":"STORE1","starting_number":100,"real_estate":{"cadastral_number":"1234","building_number":"567","building_section":"1","street":"Dunajska cesta","house_number":"22","house_number_additional":"A","community":"Ljubljana","city":"Ljubljana","postal_code":"1000"}},"description":"Register a physical store location"},"Office Location":{"value":{"business_premise_name":"OFFICE1","real_estate":{"cadastral_number":"5678","building_number":"123","building_section":"2","street":"Slovenska cesta","house_number":"10","community":"Maribor","city":"Maribor","postal_code":"2000"}},"description":"Register an office location"},"No house number suffix":{"value":{"business_premise_name":"SHOP2","real_estate":{"cadastral_number":"4321","building_number":"765","building_section":"1","street":"Trzaska cesta","house_number":"14","community":"Ljubljana","city":"Ljubljana","postal_code":"1000"}},"description":"Register a physical premise when there is no house_number_additional value."}}}}},"responses":{"200":{"description":"Real Estate Premise Registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FursPremiseSuccessResponse"},"examples":{"Success":{"value":{"success":true,"message":"Business premise registered successfully","business_premise_name":"STORE1","environment":"production"},"description":"Successfully registered real estate premise with FURS"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/furs/premises/movable":{"post":{"operationId":"registerFursMovablePremise","summary":"Register movable premise","description":"Register a movable business premise (vehicle, market stall, vending machine) with FURS (Slovenia). Required before fiscalizing invoices from this premise.","tags":["FURS Premises"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Register Movable Premise Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"business_premise_name":{"type":"string","minLength":1,"maxLength":20,"description":"Business premise name/identifier (e.g., 'VEHICLE1', 'STALL2')","example":"VEHICLE1"},"movable_premise":{"type":"object","properties":{"premise_type":{"type":"string","enum":["A","B","C"],"description":"Type of movable premise: A=vehicle, B=market stall, C=vending machine","example":"B"}},"required":["premise_type"],"description":"Movable premise details"},"starting_number":{"type":["integer","null"],"minimum":1,"maximum":999999999,"description":"Optional first fiscal invoice number for this premise/device sequence. Can only be changed before invoices have been issued for the matching fiscal sequence.","example":100}},"required":["business_premise_name","movable_premise"],"additionalProperties":false},"examples":{"Food Truck":{"value":{"business_premise_name":"TRUCK1","starting_number":100,"movable_premise":{"premise_type":"A"}},"description":"Register a food truck (vehicle)"},"Market Stall":{"value":{"business_premise_name":"STALL1","movable_premise":{"premise_type":"B"}},"description":"Register a market stall"},"Vending Machine":{"value":{"business_premise_name":"VEND1","movable_premise":{"premise_type":"C"}},"description":"Register a vending machine"},"Mobile service vehicle":{"value":{"business_premise_name":"VAN1","movable_premise":{"premise_type":"A"}},"description":"Register a mobile service vehicle used for field-service fiscalized sales."}}}}},"responses":{"200":{"description":"Movable Premise Registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FursPremiseSuccessResponse"},"examples":{"Success":{"value":{"success":true,"message":"Business premise registered successfully","business_premise_name":"TRUCK1","environment":"production"},"description":"Successfully registered movable premise with FURS"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/furs/premises/{id}/close":{"post":{"operationId":"closeFursBusinessPremise","summary":"Close business premise","description":"Close a previously registered business premise with FURS. This should be done when a business location is permanently closed.","tags":["FURS Premises"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","description":"Business premise ID","example":"premise_507f1f77bcf86cd799439011"},"required":true,"description":"Business premise ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Business Premise Closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FursPremiseSuccessResponse"},"examples":{"Success":{"value":{"success":true,"message":"Business premise closed successfully","business_premise_name":"STORE1","environment":"production"},"description":"Successfully closed business premise with FURS"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/furs/premises/{id}/devices":{"get":{"operationId":"listFursElectronicDevices","summary":"List electronic devices","description":"Retrieve all electronic devices (cash registers, POS terminals) registered for a business premise.","tags":["FURS Devices"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","description":"Business premise ID","example":"premise_507f1f77bcf86cd799439011"},"required":true,"description":"Business premise ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Electronic Devices List","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FursElectronicDevice"}},"examples":{"Electronic Devices":{"value":[]}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"registerFursElectronicDevice","summary":"Register electronic device","description":"Register an electronic device (cash register, POS terminal, etc.) for a business premise. Required before fiscalizing invoices from this device.","x-codegen-request-body-name":"body","tags":["FURS Devices"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","description":"Business premise ID","example":"premise_507f1f77bcf86cd799439011"},"required":true,"description":"Business premise ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Register Electronic Device Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":20,"description":"Electronic device name/identifier (e.g., 'E1', 'POS1', 'DEVICE1')","example":"DEVICE1"},"starting_number":{"type":["integer","null"],"minimum":1,"maximum":999999999,"description":"Optional first fiscal invoice number for this premise/device sequence. Can only be changed before invoices have been issued for the matching fiscal sequence.","example":100}},"required":["name"],"additionalProperties":false},"examples":{"POS Terminal":{"value":{"name":"DEVICE1","starting_number":100},"description":"Register a POS terminal device"}}}}},"responses":{"201":{"description":"Electronic Device Registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ElectronicDeviceSuccessResponse"},"examples":{"Device Registered":{"value":{"success":true,"message":"Electronic device registered successfully","device_name":"DEVICE1"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/furs/devices/{id}":{"get":{"operationId":"getFursElectronicDevice","summary":"Get an electronic device","description":"Retrieve details of a specific electronic device by ID.","tags":["FURS Devices"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","description":"Electronic device ID","example":"device_507f1f77bcf86cd799439011"},"required":true,"description":"Electronic device ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Electronic Device Details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FursElectronicDevice"},"examples":{"Electronic Device":{"value":{"id":"device_507f1f77bcf86cd799439011","premise_id":"premise_507f1f77bcf86cd799439011","electronic_device_name":"POS Terminal 1","is_active":true,"starting_number":100,"can_update_starting_number":true,"created_at":"2025-01-01T00:00:00.000Z","updated_at":"2025-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateFursElectronicDevice","summary":"Update an electronic device","description":"Update mutable FURS electronic device settings. The starting number can only be changed before invoices have been issued for the device-level sequence.","tags":["FURS Devices"],"security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","description":"Electronic device ID","example":"device_507f1f77bcf86cd799439011"},"required":true,"description":"Electronic device ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update FURS Electronic Device Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"starting_number":{"type":["integer","null"],"minimum":1,"maximum":999999999,"description":"Optional first fiscal invoice number for this premise/device sequence. Can only be changed before invoices have been issued for the matching fiscal sequence.","example":100}},"additionalProperties":false},"examples":{"Set starting number":{"value":{"starting_number":250},"description":"Set the next device-level invoice number before any invoices have used this sequence."},"Clear starting number":{"value":{"starting_number":null},"description":"Clear the configured device-level starting number."}}}}},"responses":{"200":{"description":"Updated Electronic Device","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FursElectronicDevice"},"examples":{"Updated Electronic Device":{"value":{"id":"device_507f1f77bcf86cd799439011","premise_id":"premise_507f1f77bcf86cd799439011","electronic_device_name":"1","is_active":true,"starting_number":250,"can_update_starting_number":true,"created_at":"2025-01-01T00:00:00.000Z","updated_at":"2025-01-02T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/fina/settings":{"get":{"operationId":"getFinaSettings","summary":"Get FINA settings","description":"Retrieve CIS fiscalization settings for the entity, including certificate status and configuration","security":[{"Bearer":[]}],"tags":["FINA Settings"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"FINA Settings","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","default":false,"description":"Whether CIS (FINA) fiscalization is enabled for this entity","example":true},"operator_oib":{"type":"string","minLength":11,"maxLength":11,"description":"OIB of the operator (11 digits). Used when creating invoices via API key.","example":"12345678901"},"operator_label":{"type":"string","description":"Operator label/name for this entity","example":"Cash Register 1"},"u_sust_pdv":{"type":"boolean","default":true,"description":"Whether the entity is in the PDV (VAT) system. Most businesses are.","example":true},"numbering_sequence":{"type":"string","enum":["N","P"],"default":"P","description":"Numbering sequence: P (per premise) or N (per device)","example":"P"},"unified_numbering":{"type":["boolean","null"],"description":"When enabled (default: true), all documents use the same FINA numbering sequence regardless of transaction type (domestic/non-domestic)","example":true},"certificate_expiry":{"type":"string","description":"Certificate expiration date"},"has_certificate":{"type":"boolean","description":"Whether a certificate is uploaded"},"certificate_status":{"type":"string","enum":["valid","expiring_soon","expired","missing"],"description":"Certificate status"}},"required":["has_certificate"]},"examples":{"Configured Settings":{"value":{"enabled":true,"operator_oib":"12345678901","operator_label":"Alex Carter","u_sust_pdv":true,"numbering_sequence":"P","certificate_expiry":"2026-12-31T23:59:59.000Z","certificate_status":"valid","has_certificate":true},"description":"FINA settings with valid certificate"},"Missing Certificate":{"value":{"enabled":false,"operator_oib":"12345678901","operator_label":"Alex Carter","u_sust_pdv":true,"numbering_sequence":"P","certificate_expiry":null,"certificate_status":"missing","has_certificate":false},"description":"FINA settings without certificate"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updateFinaSettings","summary":"Update FINA settings","description":"Update CIS fiscalization settings for the entity. Certificate must be uploaded separately via POST /fiscalization/fina/settings/certificate","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["FINA Settings"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update FINA Settings Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","default":false,"description":"Whether CIS (FINA) fiscalization is enabled for this entity","example":true},"operator_oib":{"type":"string","minLength":11,"maxLength":11,"description":"OIB of the operator (11 digits). Used when creating invoices via API key.","example":"12345678901"},"operator_label":{"type":"string","description":"Operator label/name for this entity","example":"Cash Register 1"},"u_sust_pdv":{"type":"boolean","default":true,"description":"Whether the entity is in the PDV (VAT) system. Most businesses are.","example":true},"numbering_sequence":{"type":"string","enum":["N","P"],"default":"P","description":"Numbering sequence: P (per premise) or N (per device)","example":"P"},"unified_numbering":{"type":["boolean","null"],"description":"When enabled (default: true), all documents use the same FINA numbering sequence regardless of transaction type (domestic/non-domestic)","example":true}},"additionalProperties":false},"examples":{"Enable CIS":{"value":{"enabled":true,"operator_oib":"12345678901","operator_label":"Alex Carter","u_sust_pdv":true,"numbering_sequence":"P"},"description":"Enable CIS fiscalization with per-premise numbering"},"Update Operator":{"value":{"operator_oib":"98765432109","operator_label":"New Operator"},"description":"Update operator OIB and label"},"Per-device numbering":{"value":{"numbering_sequence":"N"},"description":"Use per-device CIS numbering when each fiscal device maintains its own sequence."},"Disable CIS":{"value":{"enabled":false},"description":"Disable Croatian CIS fiscalization for the entity."}}}}},"responses":{"200":{"description":"FINA Settings Updated","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","default":false,"description":"Whether CIS (FINA) fiscalization is enabled for this entity","example":true},"operator_oib":{"type":"string","minLength":11,"maxLength":11,"description":"OIB of the operator (11 digits). Used when creating invoices via API key.","example":"12345678901"},"operator_label":{"type":"string","description":"Operator label/name for this entity","example":"Cash Register 1"},"u_sust_pdv":{"type":"boolean","default":true,"description":"Whether the entity is in the PDV (VAT) system. Most businesses are.","example":true},"numbering_sequence":{"type":"string","enum":["N","P"],"default":"P","description":"Numbering sequence: P (per premise) or N (per device)","example":"P"},"unified_numbering":{"type":["boolean","null"],"description":"When enabled (default: true), all documents use the same FINA numbering sequence regardless of transaction type (domestic/non-domestic)","example":true},"certificate_expiry":{"type":"string","description":"Certificate expiration date"},"has_certificate":{"type":"boolean","description":"Whether a certificate is uploaded"},"certificate_status":{"type":"string","enum":["valid","expiring_soon","expired","missing"],"description":"Certificate status"}},"required":["has_certificate"]},"examples":{"Configured Settings":{"value":{"enabled":true,"operator_oib":"12345678901","operator_label":"Alex Carter","u_sust_pdv":true,"numbering_sequence":"P","certificate_expiry":"2026-12-31T23:59:59.000Z","certificate_status":"valid","has_certificate":true},"description":"FINA settings with valid certificate"},"Missing Certificate":{"value":{"enabled":false,"operator_oib":"12345678901","operator_label":"Alex Carter","u_sust_pdv":true,"numbering_sequence":"P","certificate_expiry":null,"certificate_status":"missing","has_certificate":false},"description":"FINA settings without certificate"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/fina/settings/certificate":{"post":{"operationId":"uploadFinaCertificate","summary":"Upload FINA certificate","description":"Upload a P12/PFX certificate for CIS fiscalization. The certificate will be processed to extract expiry date and stored securely.","security":[{"Bearer":[]}],"tags":["FINA Certificate"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"P12/PFX certificate file","format":"binary"},"passphrase":{"type":"string","description":"Certificate passphrase (will be encrypted before storage)","example":"my-secure-passphrase"}}}}}},"responses":{"200":{"description":"Certificate Uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"certificate_expiry":{"type":"string","format":"date-time","description":"Certificate expiration date (ISO 8601 format)","example":"2026-12-31T00:00:00Z"},"message":{"type":"string","description":"Success message","example":"Certificate uploaded and processed successfully"}},"required":["certificate_expiry","message"]},"examples":{"Success":{"value":{"certificate_expiry":"2026-12-31T23:59:59.000Z","certificate_cn":"12345678901","certificate_issuer":"FINA RDC 2015","uploaded_at":"2025-06-15T10:30:00.000Z","message":"Certificate uploaded and validated successfully"},"description":"Successfully uploaded FINA certificate"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getFinaCertificate","summary":"Get certificate metadata","description":"Retrieve certificate metadata including expiry date and upload time. Does not return the certificate or private key.","security":[{"Bearer":[]}],"tags":["FINA Certificate"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"FINA Certificate Metadata","content":{"application/json":{"schema":{"type":"object","properties":{"certificate_expiry":{"type":"string"},"certificate_cn":{"type":["string","null"]},"certificate_issuer":{"type":["string","null"]},"uploaded_at":{"type":"string"},"message":{"type":"string"}},"required":["certificate_expiry","certificate_cn","certificate_issuer","uploaded_at","message"]},"examples":{"Success":{"value":{"certificate_expiry":"2026-12-31T23:59:59.000Z","certificate_cn":"12345678901","certificate_issuer":"FINA RDC 2015","uploaded_at":"2025-06-15T10:30:00.000Z","message":"Certificate uploaded and validated successfully"},"description":"Successfully uploaded FINA certificate"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteFinaCertificate","summary":"Delete FINA certificate","description":"Delete the FINA certificate for the entity. This will remove both the uploaded file reference and the extracted certificate from the database.","security":[{"Bearer":[]}],"tags":["FINA Certificate"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Certificate deleted successfully"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/fina/premises":{"get":{"operationId":"listFinaPremises","summary":"List business premises","description":"List all business premises for the entity","security":[{"Bearer":[]}],"tags":["FINA Premises"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"FINA Premises","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FinaBusinessPremise"}},"examples":{"Business Premises":{"value":[]}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createFinaPremise","summary":"Create business premise","description":"Add a business premise for FINA fiscalization. The premise must be registered on ePorezna first. Only the premise ID label is stored.","security":[{"Bearer":[]}],"tags":["FINA Premises"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Create Premise","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"business_premise_name":{"type":"string","minLength":1,"maxLength":20,"pattern":"^[0-9a-zA-Z]{1,20}$","description":"Business premise name (OznPosPr), alphanumeric, 1-20 chars. Must match the name registered on ePorezna.","example":"PP1"},"starting_number":{"type":["integer","null"],"minimum":1,"maximum":999999999,"description":"Optional first fiscal invoice number for this premise/device sequence. Can only be changed before invoices have been issued for the matching fiscal sequence.","example":100}},"required":["business_premise_name"],"additionalProperties":false},"examples":{"Physical Store":{"value":{"business_premise_name":"PP1","starting_number":100},"description":"Add a business premise name (must be registered on ePorezna first)"},"Office Location":{"value":{"business_premise_name":"OFFICE1"},"description":"Add an office location premise"},"Web checkout premise":{"value":{"business_premise_name":"WEB1"},"description":"Add a premise code used for online/card payments that still require CIS fiscalization."}}}}},"responses":{"201":{"description":"Premise Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinaPremiseSuccessResponse"},"examples":{"Success":{"value":{"success":true,"message":"Business premise created successfully","business_premise_name":"PP1"},"description":"Successfully created business premise"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/fina/premises/{id}":{"get":{"operationId":"getFinaPremise","summary":"Get business premise","description":"Get a single business premise by ID","security":[{"Bearer":[]}],"tags":["FINA Premises"],"parameters":[{"schema":{"type":"string","description":"Premise ID"},"required":true,"description":"Premise ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"FINA Premise","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinaBusinessPremise"},"examples":{"Business Premise":{"value":{"id":"fina_premise_507f1f77bcf86cd799439011","entity_id":"ent_507f1f77bcf86cd799439011","business_premise_name":"PP1","type":"premise","real_estate":null,"movable_premise":null,"is_active":true,"registered_at":"2025-01-01T00:00:00.000Z","closed_at":null,"created_at":"2025-01-01T00:00:00.000Z","updated_at":"2025-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateFinaPremise","summary":"Update business premise","description":"Update mutable FINA premise settings. The starting number can only be changed before invoices have been issued for the premise-level sequence.","security":[{"Bearer":[]}],"tags":["FINA Premises"],"parameters":[{"schema":{"type":"string","description":"Premise ID"},"required":true,"description":"Premise ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update FINA Premise","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"starting_number":{"type":["integer","null"],"minimum":1,"maximum":999999999,"description":"Optional first fiscal invoice number for this premise/device sequence. Can only be changed before invoices have been issued for the matching fiscal sequence.","example":100}},"additionalProperties":false},"examples":{"Set starting number":{"value":{"starting_number":250},"description":"Set the next premise-level invoice number before any invoices have used this sequence."},"Clear starting number":{"value":{"starting_number":null},"description":"Clear the configured premise-level starting number."}}}}},"responses":{"200":{"description":"Updated FINA Premise","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinaBusinessPremise"},"examples":{"Updated FINA Premise":{"value":{"id":"fina_premise_507f1f77bcf86cd799439011","entity_id":"ent_507f1f77bcf86cd799439011","business_premise_name":"PP1","type":"premise","real_estate":null,"movable_premise":null,"is_active":true,"starting_number":250,"registered_at":"2025-01-01T00:00:00.000Z","closed_at":null,"created_at":"2025-01-01T00:00:00.000Z","updated_at":"2025-01-02T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteFinaPremise","summary":"Delete business premise","description":"Deactivate a business premise and all its devices.","security":[{"Bearer":[]}],"tags":["FINA Premises"],"parameters":[{"schema":{"type":"string","description":"Premise ID","example":"fina_premise_abc123"},"required":true,"description":"Premise ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Premise Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinaPremiseSuccessResponse"},"examples":{"Success":{"value":{"success":true,"message":"Business premise deactivated successfully","business_premise_name":"PP1"},"description":"Successfully deactivated business premise"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/fina/premises/{id}/devices":{"get":{"operationId":"listFinaDevices","summary":"List electronic devices","description":"List all electronic devices for a business premise","security":[{"Bearer":[]}],"tags":["FINA Devices"],"parameters":[{"schema":{"type":"string","description":"Premise ID"},"required":true,"description":"Premise ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"FINA Devices","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FinaElectronicDevice"}},"examples":{"Electronic Devices":{"value":[]}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"registerFinaDevice","summary":"Register electronic device","description":"Register an electronic device (cash register, POS) for a business premise. Device ID must be digits only.","security":[{"Bearer":[]}],"tags":["FINA Devices"],"parameters":[{"schema":{"type":"string","description":"Premise ID"},"required":true,"description":"Premise ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Register Electronic Device","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"electronic_device_name":{"type":"string","minLength":1,"maxLength":20,"pattern":"^\\d{1,20}$","description":"Electronic device name (OznNapUr), digits only, 1-20 chars","example":"1"},"starting_number":{"type":["integer","null"],"minimum":1,"maximum":999999999,"description":"Optional first fiscal invoice number for this premise/device sequence. Can only be changed before invoices have been issued for the matching fiscal sequence.","example":100}},"required":["electronic_device_name"],"additionalProperties":false},"examples":{"POS Terminal":{"value":{"electronic_device_name":"1","starting_number":100},"description":"Register a POS terminal device"},"Online checkout device":{"value":{"electronic_device_name":"2"},"description":"Register a separate electronic device for web checkout or kiosk-originated invoices."}}}}},"responses":{"201":{"description":"Device Registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinaElectronicDeviceSuccessResponse"},"examples":{"Device Registered":{"value":{"success":true,"message":"Electronic device registered successfully","electronic_device_name":"1"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/fina/devices/{id}":{"get":{"operationId":"getFinaDevice","summary":"Get electronic device","description":"Get a single electronic device by ID","security":[{"Bearer":[]}],"tags":["FINA Devices"],"parameters":[{"schema":{"type":"string","description":"Device ID"},"required":true,"description":"Device ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"FINA Device","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinaElectronicDevice"},"examples":{"Electronic Device":{"value":{"id":"fina_device_507f1f77bcf86cd799439011","premise_id":"fina_premise_507f1f77bcf86cd799439011","electronic_device_name":"1","is_active":true,"created_at":"2025-01-01T00:00:00.000Z","updated_at":"2025-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateFinaDevice","summary":"Update electronic device","description":"Update mutable FINA electronic device settings. The starting number can only be changed before invoices have been issued for the device-level sequence.","security":[{"Bearer":[]}],"tags":["FINA Devices"],"parameters":[{"schema":{"type":"string","description":"Device ID"},"required":true,"description":"Device ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update FINA Device","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"starting_number":{"type":["integer","null"],"minimum":1,"maximum":999999999,"description":"Optional first fiscal invoice number for this premise/device sequence. Can only be changed before invoices have been issued for the matching fiscal sequence.","example":100}},"additionalProperties":false},"examples":{"Set starting number":{"value":{"starting_number":250},"description":"Set the next device-level invoice number before any invoices have used this sequence."},"Clear starting number":{"value":{"starting_number":null},"description":"Clear the configured device-level starting number."}}}}},"responses":{"200":{"description":"Updated FINA Device","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinaElectronicDevice"},"examples":{"Updated FINA Device":{"value":{"id":"fina_device_507f1f77bcf86cd799439011","premise_id":"fina_premise_507f1f77bcf86cd799439011","electronic_device_name":"1","is_active":true,"starting_number":250,"created_at":"2025-01-01T00:00:00.000Z","updated_at":"2025-01-02T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteFinaDevice","summary":"Delete electronic device","description":"Deactivate an electronic device.","security":[{"Bearer":[]}],"tags":["FINA Devices"],"parameters":[{"schema":{"type":"string","description":"Device ID"},"required":true,"description":"Device ID","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Device Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinaElectronicDeviceSuccessResponse"},"examples":{"Success":{"value":{"success":true,"message":"Electronic device deactivated successfully","electronic_device_name":"1"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/pt/atcud-series":{"post":{"operationId":"createPtAtcudSeries","summary":"Create PT ATCUD series","description":"Create a Portugal ATCUD series registration for one PT document type.","security":[{"Bearer":[]}],"tags":["PT ATCUD Series"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Create PT ATCUD Series","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"document_type":{"type":"string","enum":["invoice","advance_invoice","credit_note","estimate"],"description":"Portugal fiscal document type tracked for ATCUD series numbering.","example":"invoice"},"series_code":{"type":"string","minLength":1,"maxLength":35,"description":"AT-communicated series code used in the PT document number.","example":"FT 2026/A"},"validation_code":{"type":"string","minLength":1,"maxLength":32,"description":"Validation code assigned by AT for the communicated series.","example":"AB12CD34EF"},"first_number":{"type":"string","minLength":1,"maxLength":100,"description":"Legacy/legal first document number registered for this ATCUD series.","example":"FT FT2026A/00001"},"start_date":{"type":"string","format":"date","description":"First date for which the communicated series is valid.","example":"2026-01-01"},"is_manual":{"type":"boolean","description":"Whether this series is reserved for manually issued PT documents.","example":false},"initial_sequence":{"type":"integer","minimum":1,"description":"Initial PT legal sequence number for this series.","example":1}},"required":["document_type","series_code","validation_code","start_date"],"additionalProperties":false},"examples":{"Minimal":{"value":{"document_type":"invoice","series_code":"FT 2026/A","validation_code":"AB12CD34EF","first_number":"FT FT2026A/00001","start_date":"2026-01-01","is_manual":false,"initial_sequence":1},"description":"Create the active ATCUD series used for generated PT invoices."},"Manual credit note series":{"value":{"document_type":"credit_note","series_code":"NC MANUAL","validation_code":"ZX98YU76TR","first_number":"NC MANUAL/00001","start_date":"2026-01-01","is_manual":true,"initial_sequence":1},"description":"Create a manual/offline ATCUD series for imported Portuguese credit notes."}}}}},"responses":{"201":{"description":"Created PT ATCUD series","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PtAtcudSeries"},"example":{"id":"pt_series_000000000000000000000001","entity_id":"ent_000000000000000000000001","document_type":"invoice","series_code":"FT 2026/A","validation_code":"AB12CD34EF","first_number":"FT FT2026A/00001","start_date":"2026-01-01","is_manual":false,"initial_sequence":1}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listPtAtcudSeries","summary":"List PT ATCUD series","description":"List PT ATCUD series registered on the selected PT entity.","security":[{"Bearer":[]}],"tags":["PT ATCUD Series"],"parameters":[{"schema":{"type":"string","enum":["invoice","advance_invoice","credit_note","estimate"]},"required":false,"name":"document_type","in":"query"},{"schema":{"type":["boolean","null"]},"required":false,"name":"is_manual","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"PT ATCUD series","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PtAtcudSeries"}},"example":[{"id":"pt_series_000000000000000000000001","entity_id":"ent_000000000000000000000001","document_type":"invoice","series_code":"FT 2026/A","validation_code":"AB12CD34EF","first_number":"FT FT2026A/00001","start_date":"2026-01-01","is_manual":false,"initial_sequence":1}]}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/pt/atcud-series/{id}":{"get":{"operationId":"getPtAtcudSeries","summary":"Get PT ATCUD series","description":"Get one PT ATCUD series by ID.","security":[{"Bearer":[]}],"tags":["PT ATCUD Series"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^(?:[a-z]{3,4}_){0,2}[0-9a-f]{24}$","description":"Space Invoices resource identifier (format: {prefix}_{hex24})","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Space Invoices resource identifier (format: {prefix}_{hex24})","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"PT ATCUD series","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PtAtcudSeries"},"example":{"id":"pt_series_000000000000000000000001","entity_id":"ent_000000000000000000000001","document_type":"invoice","series_code":"FT 2026/A","validation_code":"AB12CD34EF","first_number":"FT FT2026A/00001","start_date":"2026-01-01","is_manual":false,"initial_sequence":1}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/pt/atcud-series/active":{"post":{"operationId":"getActivePtAtcudSeries","summary":"Get active PT ATCUD series","description":"Return the current non-manual PT ATCUD series by document type, matching the legacy active-series lookup.","security":[{"Bearer":[]}],"tags":["PT ATCUD Series"],"parameters":[{"schema":{"type":"string","enum":["invoice","advance_invoice","credit_note","estimate"]},"required":false,"name":"document_type","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Active PT ATCUD series","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PtAtcudSeries"}},"example":[{"id":"pt_series_000000000000000000000001","entity_id":"ent_000000000000000000000001","document_type":"invoice","series_code":"FT 2026/A","validation_code":"AB12CD34EF","first_number":"FT FT2026A/00001","start_date":"2026-01-01","is_manual":false,"initial_sequence":1}]}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/fiscalization/pt/saft/report":{"get":{"operationId":"generatePtSaftReport","summary":"Generate PT SAF-T report","description":"Generate a Portugal SAF-T XML export for the selected PT entity. The response is encoded as windows-1252 for AT/audit compatibility.","security":[{"Bearer":[]}],"tags":["PT SAF-T"],"parameters":[{"schema":{"type":"string","format":"date","example":"2026-01-01","description":"Report start date (inclusive) in YYYY-MM-DD format."},"required":false,"description":"Report start date (inclusive) in YYYY-MM-DD format.","name":"from","in":"query"},{"schema":{"type":"string","format":"date","example":"2026-01-31","description":"Report end date (inclusive) in YYYY-MM-DD format."},"required":false,"description":"Report end date (inclusive) in YYYY-MM-DD format.","name":"to","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Portugal SAF-T XML file","content":{"application/xml":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transaction-type/check":{"post":{"operationId":"checkTransactionType","summary":"Check transaction type","description":"Check transaction type and reverse charge applicability based on issuer and customer information.\n\n**Country Resolution:**\n- Country names are automatically resolved to ISO country codes (handles variations like \"Slovenija\" → \"SI\")\n- If both country and country_code are provided, country_code takes precedence\n\n**Transaction Types:**\n- `domestic`: Same country for issuer and customer\n- `intra_eu_b2b`: Cross-border EU sale to business with valid tax number\n- `intra_eu_b2c`: Cross-border EU sale to consumer (no tax number)\n- `3w_b2b`: Non-EU sale to business (with tax number)\n- `3w_b2c`: Non-EU sale to consumer (no tax number, or is_end_consumer=true)\n\n**Reverse Charge:**\nApplies when:\n- Issuer is an EU tax subject\n- Customer is in a different EU country with valid tax number, OR customer is outside EU\n\n**End Consumer Override:**\nWhen customer.is_end_consumer is true, forces B2C classification for non-EU transactions even if the customer has a tax number. For intra-EU transactions, VIES validation takes precedence.\n\n**Non-Tax Subjects:**\nWhen issuer.is_tax_subject is false, all transactions are treated as B2C (no VIES validation, no reverse charge).","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Transaction Type"],"requestBody":{"description":"Transaction Type Check Request","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionTypeCheckRequest"},"examples":{"IntraEuB2B":{"value":{"issuer":{"country":"Slovenia","is_tax_subject":true},"customer":{"country":"Germany","tax_number":"DE123456789"}}},"Domestic":{"value":{"issuer":{"country":"Slovenia"},"customer":{"country":"Slovenia"}}},"ThirdWorldB2C":{"value":{"issuer":{"country_code":"HR","is_tax_subject":true},"customer":{"country_code":"US"}}},"ThirdWorldB2B":{"value":{"issuer":{"country_code":"SI","is_tax_subject":true},"customer":{"country_code":"US","tax_number":"123456789"}}},"IntraEuB2C":{"value":{"issuer":{"country_code":"SI","is_tax_subject":true},"customer":{"country_code":"DE","is_end_consumer":true}}},"NonTaxSubjectIssuer":{"value":{"issuer":{"country_code":"SI","is_tax_subject":false},"customer":{"country_code":"AT","tax_number":"ATU12345678"}}}}}}},"responses":{"200":{"description":"Transaction Type Check Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionTypeCheckResponse"},"examples":{"IntraEuB2B":{"value":{"transaction_type":"intra_eu_b2b","reverse_charge_applies":true,"issuer_country_code":"SI","customer_country_code":"DE","vies_valid":true,"warning":null,"is_tax_subject":true}},"Domestic":{"value":{"transaction_type":"domestic","reverse_charge_applies":false,"issuer_country_code":"SI","customer_country_code":"SI","vies_valid":null,"warning":null,"is_tax_subject":true}},"ThirdWorldB2C":{"value":{"transaction_type":"3w_b2c","reverse_charge_applies":true,"issuer_country_code":"HR","customer_country_code":"US","vies_valid":null,"warning":null}},"ThirdWorldB2B":{"value":{"transaction_type":"3w_b2b","reverse_charge_applies":true,"issuer_country_code":"SI","customer_country_code":"US","vies_valid":null,"warning":null}},"IntraEuB2C":{"value":{"transaction_type":"intra_eu_b2c","reverse_charge_applies":false,"issuer_country_code":"SI","customer_country_code":"DE","vies_valid":null,"warning":null,"is_tax_subject":true}},"NonTaxSubjectIssuer":{"value":{"transaction_type":"intra_eu_b2c","reverse_charge_applies":false,"issuer_country_code":"SI","customer_country_code":"AT","vies_valid":null,"warning":"Issuer is not a tax subject; VIES and reverse charge do not apply.","is_tax_subject":false}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/vies/check":{"post":{"operationId":"checkVies","deprecated":true,"summary":"Check VIES status (deprecated)","description":"**Deprecated:** Use `POST /transaction-type/check` instead. This endpoint is kept for backward compatibility.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["VIES"],"requestBody":{"description":"VIES Check Request","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionTypeCheckRequest"},"examples":{"IntraEuB2B":{"value":{"issuer":{"country_code":"SI","is_tax_subject":true},"customer":{"country_code":"DE","tax_number":"DE123456789"}}}}}}},"responses":{"200":{"description":"VIES Check Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionTypeCheckResponse"},"examples":{"IntraEuB2B":{"value":{"transaction_type":"intra_eu_b2b","reverse_charge_applies":true,"issuer_country_code":"SI","customer_country_code":"DE","vies_valid":true,"warning":null,"is_tax_subject":true}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/eslog/{documentId}/validate":{"post":{"operationId":"validateDocumentEslog","summary":"Validate document for e-SLOG","description":"Manually trigger e-SLOG 2.0 validation for a document.\nUpdates the document's `eslog` field with validation status.\nOnly available for Slovenian entities.","security":[{"Bearer":[]}],"tags":["e-SLOG"],"parameters":[{"schema":{"type":"string","description":"Document ID (invoice, estimate, credit note, or advance invoice)","example":"inv_clx1234567890"},"required":true,"description":"Document ID (invoice, estimate, credit note, or advance invoice)","name":"documentId","in":"path"},{"schema":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice"],"description":"Document type","example":"invoice"},"required":true,"description":"Document type","name":"type","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EslogValidationResponse"},"examples":{"ValidInvoice":{"value":{"document_id":"inv_clx1234567890","document_type":"invoice","eslog":{"validation_enabled":true,"validation_status":"valid","validation_errors":[],"validated_at":"2025-01-15T10:30:00.000Z"}},"description":"Document is ready to download as native e-SLOG XML."},"MissingPrerequisites":{"value":{"document_id":"inv_clx1234567890","document_type":"invoice","eslog":{"validation_enabled":true,"validation_status":"invalid","validation_errors":["Customer bank account is required for Slovenian B2G e-SLOG export."],"validated_at":"2025-01-15T10:30:00.000Z"}},"description":"Document failed validation with user-fixable prerequisites."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/eslog/{documentId}/download":{"get":{"operationId":"downloadDocumentEslog","summary":"Download e-SLOG XML","description":"Download a validated document as native e-SLOG 2.0 XML.","security":[{"Bearer":[]}],"tags":["e-SLOG"],"parameters":[{"schema":{"type":"string","description":"Document ID (invoice, estimate, credit note, or advance invoice)","example":"inv_clx1234567890"},"required":true,"description":"Document ID (invoice, estimate, credit note, or advance invoice)","name":"documentId","in":"path"},{"schema":{"type":"string","enum":["invoice","estimate","credit_note","advance_invoice"],"description":"Document type","example":"invoice"},"required":true,"description":"Document type","name":"type","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"e-SLOG 2.0 XML document","content":{"application/xml":{"schema":{"type":"string","description":"e-SLOG 2.0 XML content"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents/{id}/ujp":{"get":{"operationId":"downloadUjpPackage","summary":"Download UJP package","description":"Download a deterministic ZIP package for Slovenian UJP provider or B2B e-invoice exchange. The document type is detected from the ID prefix. This does not send the document and does not require UJP credentials or certificates. The package requires current valid e-SLOG XML, a UJP `.env` envelope, a `.tar.gz` attachment package hashed by the envelope, and a PDF visualization.","security":[{"Bearer":[]}],"tags":["UJP"],"parameters":[{"schema":{"type":"string","description":"Document ID. The document type is detected from the ID prefix.","example":"inv_clx1234567890"},"required":true,"description":"Document ID. The document type is detected from the ID prefix.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"UJP package ZIP containing e-SLOG XML, UJP .env envelope, tar.gz attachment package, and PDF visualization","content":{"application/zip":{"schema":{"type":"string","format":"binary","description":"ZIP archive"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/e-invoicing/settings":{"get":{"operationId":"getEInvoicingSettings","summary":"Get e-invoicing settings","description":"Get the current e-invoicing settings and enrollment state for the entity.","security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"E-invoicing settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSettingsResponse"},"example":{"enabled":true,"auto_send":false,"enrollment":{"id":"einv_enr_1234567890","entity_id":"ent_1234567890","environment":"sandbox","verification_url":null,"last_synced_at":"2026-06-24T12:00:00.000Z","peppol_registered":true,"peppol_id":"12345678","peppol_scheme_id":"0009","verified_at":"2026-06-24T12:00:00.000Z","state":"verified","sending_allowed":true,"missing_fields":[],"provider_error":null}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateEInvoicingSettings","summary":"Update e-invoicing settings","description":"Enable or disable Peppol sending and configure automatic sending for the entity.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update E-Invoicing Settings","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEInvoicingSettingsRequest"},"example":{"enabled":true,"auto_send":false}}}},"responses":{"200":{"description":"Updated settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSettingsResponse"},"example":{"enabled":true,"auto_send":false,"enrollment":{"id":"einv_enr_1234567890","entity_id":"ent_1234567890","environment":"sandbox","verification_url":null,"last_synced_at":"2026-06-24T12:00:00.000Z","peppol_registered":true,"peppol_id":"12345678","peppol_scheme_id":"0009","verified_at":"2026-06-24T12:00:00.000Z","state":"verified","sending_allowed":true,"missing_fields":[],"provider_error":null}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/e-invoicing/enrollment/sync":{"post":{"operationId":"syncEInvoicingEnrollment","summary":"Sync enrollment","description":"Refresh the entity enrollment state from the Peppol sending provider.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Synced settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSettingsResponse"},"example":{"enabled":true,"auto_send":false,"enrollment":{"id":"einv_enr_1234567890","entity_id":"ent_1234567890","environment":"sandbox","verification_url":null,"last_synced_at":"2026-06-24T12:00:00.000Z","peppol_registered":true,"peppol_id":"12345678","peppol_scheme_id":"0009","verified_at":"2026-06-24T12:00:00.000Z","state":"verified","sending_allowed":true,"missing_fields":[],"provider_error":null}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/e-invoicing/enrollment/verification-link":{"post":{"operationId":"createEInvoicingVerificationLink","summary":"Create verification link","description":"Create a fresh verification link for the entity enrollment when verification is required.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Settings with verification link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSettingsResponse"},"example":{"enabled":true,"auto_send":false,"enrollment":{"id":"einv_enr_1234567890","entity_id":"ent_1234567890","environment":"sandbox","verification_url":"https://example.com/e-invoicing/verify/abc123","last_synced_at":"2026-06-24T12:00:00.000Z","peppol_registered":true,"peppol_id":"12345678","peppol_scheme_id":"0009","verified_at":"2026-06-24T12:00:00.000Z","state":"verification_required","sending_allowed":false,"missing_fields":[],"provider_error":null}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/e-invoicing/supplier":{"post":{"operationId":"registerEInvoicingSupplier","summary":"Register supplier (deprecated)","description":"Deprecated compatibility alias. Use PATCH /e-invoicing/settings to enable Peppol sending.","deprecated":true,"x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Register Supplier","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterEInvoicingSupplierRequest"},"example":{"company_name":"Client Corp SARL","vat_number":"FR12345678901","country_code":"FR"}}}},"responses":{"201":{"description":"Supplier registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSupplier"},"example":{"id":"einv_enr_1234567890","entity_id":"ent_1234567890","environment":"sandbox","status":"onboarded","peppol_registered":true,"peppol_participant_id":"98765432109876","peppol_scheme_id":"0009","company_name":"Client Corp SARL","vat_number":"FR12345678901","country_code":"FR","metadata":{},"onboarded_at":"2026-06-24T12:00:00.000Z","created_at":"2026-06-24T11:00:00.000Z","updated_at":"2026-06-24T12:00:00.000Z"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getEInvoicingSupplier","summary":"Get supplier status (deprecated)","description":"Deprecated compatibility alias. Use GET /e-invoicing/settings for enrollment state.","deprecated":true,"security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Supplier status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSupplier"},"example":{"id":"einv_enr_1234567890","entity_id":"ent_1234567890","environment":"sandbox","status":"onboarded","peppol_registered":true,"peppol_participant_id":"98765432109876","peppol_scheme_id":"0009","company_name":"Client Corp SARL","vat_number":"FR12345678901","country_code":"FR","metadata":{},"onboarded_at":"2026-06-24T12:00:00.000Z","created_at":"2026-06-24T11:00:00.000Z","updated_at":"2026-06-24T12:00:00.000Z"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateEInvoicingSupplier","summary":"Update supplier (deprecated)","description":"Deprecated compatibility alias. Entity profile data is canonical for Peppol enrollment.","deprecated":true,"x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Supplier","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEInvoicingSupplierRequest"},"example":{"contact_email":"billing@client-corp.example"}}}},"responses":{"200":{"description":"Updated supplier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSupplier"},"example":{"id":"einv_enr_1234567890","entity_id":"ent_1234567890","environment":"sandbox","status":"onboarded","peppol_registered":true,"peppol_participant_id":"98765432109876","peppol_scheme_id":"0009","company_name":"Client Corp SARL","vat_number":"FR12345678901","country_code":"FR","metadata":{},"onboarded_at":"2026-06-24T12:00:00.000Z","created_at":"2026-06-24T11:00:00.000Z","updated_at":"2026-06-24T12:00:00.000Z"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/e-invoicing/recipients/check":{"post":{"operationId":"checkEInvoicingRecipient","summary":"Check Peppol recipient","description":"Normalize a Peppol address and check registration and optional document type support.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Check Recipient","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckEInvoicingRecipientRequest"},"example":{"peppol_id":"0009:98765432109876","document_type":"invoice"}}}},"responses":{"200":{"description":"Recipient check result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingRecipientCheckResponse"},"example":{"peppol_id":"98765432109876","scheme_id":"0009","peppol_address":"0009:98765432109876","registered":true,"name":"Client Corp SARL","document_type":"invoice","document_supported":true}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/e-invoicing/customer-search":{"post":{"operationId":"searchEInvoicingCustomer","summary":"Search Peppol customer (deprecated)","description":"Deprecated compatibility alias. Use POST /e-invoicing/recipients/check.","deprecated":true,"x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Customer Search","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingCustomerSearchRequest"},"example":{"peppol_id":"98765432109876","scheme_id":"0009"}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EInvoicingCustomerSearchResult"}}},"required":["data"]},"example":{"data":[{"peppol_id":"98765432109876","scheme_id":"0009","name":"Client Corp SARL","country_code":"FR","registered":true}]}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/e-invoicing/documents/{id}/send":{"post":{"operationId":"sendEInvoicingDocument","summary":"Send document","description":"Send an invoice or credit note over Peppol. The document type is derived from the ID prefix.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Invoice or credit note ID. The document type is derived from the ID prefix.","example":"inv_123"},"required":true,"description":"Invoice or credit note ID. The document type is derived from the ID prefix.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Send E-Invoice","required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEInvoiceRequest"},"example":{"recipient_peppol_id":"0009:98765432109876","recipient_name":"Client Corp SARL"}}}},"responses":{"201":{"description":"Submission created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSubmission"},"example":{"id":"einv_sub_1234567890","entity_id":"ent_1234567890","environment":"sandbox","document_id":"inv_1234567890","document_type":"invoice","transmission_id":"msg_1234567890","recipient_peppol_id":"98765432109876","recipient_scheme_id":"0009","recipient_name":"Client Corp SARL","status":"submitted","error_message":null,"metadata":{},"submitted_at":"2026-06-24T12:10:00.000Z","delivered_at":null,"created_at":"2026-06-24T12:10:00.000Z","updated_at":"2026-06-24T12:10:00.000Z"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/e-invoicing/send/:documentType/:documentId":{"post":{"operationId":"sendEInvoice","summary":"Send e-invoice (deprecated)","description":"Deprecated compatibility alias. Use POST /e-invoicing/documents/{id}/send.","deprecated":true,"x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","enum":["invoice","credit_note"]},"required":true,"name":"documentType","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"documentId","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Send E-Invoice","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEInvoiceRequest"},"example":{"recipient_peppol_id":"98765432109876","recipient_scheme_id":"0009","recipient_name":"Client Corp SARL"}}}},"responses":{"201":{"description":"Submission created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSubmission"},"example":{"id":"einv_sub_1234567890","entity_id":"ent_1234567890","environment":"sandbox","document_id":"inv_1234567890","document_type":"invoice","transmission_id":"msg_1234567890","recipient_peppol_id":"98765432109876","recipient_scheme_id":"0009","recipient_name":"Client Corp SARL","status":"submitted","error_message":null,"metadata":{},"submitted_at":"2026-06-24T12:10:00.000Z","delivered_at":null,"created_at":"2026-06-24T12:10:00.000Z","updated_at":"2026-06-24T12:10:00.000Z"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/e-invoicing/submissions":{"get":{"operationId":"listEInvoicingSubmissions","summary":"List submissions","description":"List e-invoice submissions with pagination.","security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of submissions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EInvoicingSubmission"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"example":{"data":[{"id":"einv_sub_1234567890","entity_id":"ent_1234567890","environment":"sandbox","document_id":"inv_1234567890","document_type":"invoice","transmission_id":"msg_1234567890","recipient_peppol_id":"98765432109876","recipient_scheme_id":"0009","recipient_name":"Client Corp SARL","status":"submitted","error_message":null,"metadata":{},"submitted_at":"2026-06-24T12:10:00.000Z","delivered_at":null,"created_at":"2026-06-24T12:10:00.000Z","updated_at":"2026-06-24T12:10:00.000Z"}],"has_more":false,"next_cursor":null,"prev_cursor":null,"total_count":1}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/e-invoicing/submissions/{id}":{"get":{"operationId":"getEInvoicingSubmissionById","summary":"Get submission detail","description":"Get detailed submission status including UBL XML.","security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Submission detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSubmissionDetail"},"example":{"id":"einv_sub_1234567890","entity_id":"ent_1234567890","environment":"sandbox","document_id":"inv_1234567890","document_type":"invoice","transmission_id":"msg_1234567890","recipient_peppol_id":"98765432109876","recipient_scheme_id":"0009","recipient_name":"Client Corp SARL","status":"submitted","error_message":null,"metadata":{},"submitted_at":"2026-06-24T12:10:00.000Z","delivered_at":null,"created_at":"2026-06-24T12:10:00.000Z","updated_at":"2026-06-24T12:10:00.000Z","ubl_xml":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><Invoice />"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/e-invoicing/submissions/{id}/retry":{"post":{"operationId":"retryEInvoicingSubmissionById","summary":"Retry failed submission","description":"Retry a failed or rejected e-invoice submission.","security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Retried submission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSubmission"},"example":{"id":"einv_sub_1234567890","entity_id":"ent_1234567890","environment":"sandbox","document_id":"inv_1234567890","document_type":"invoice","transmission_id":"msg_1234567890","recipient_peppol_id":"98765432109876","recipient_scheme_id":"0009","recipient_name":"Client Corp SARL","status":"submitted","error_message":null,"metadata":{},"submitted_at":"2026-06-24T12:10:00.000Z","delivered_at":null,"created_at":"2026-06-24T12:10:00.000Z","updated_at":"2026-06-24T12:10:00.000Z"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/e-invoicing/submissions/:id":{"get":{"operationId":"getEInvoicingSubmission","summary":"Get submission detail (deprecated path)","deprecated":true,"security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Submission detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSubmissionDetail"},"example":{"id":"einv_sub_1234567890","entity_id":"ent_1234567890","environment":"sandbox","document_id":"inv_1234567890","document_type":"invoice","transmission_id":"msg_1234567890","recipient_peppol_id":"98765432109876","recipient_scheme_id":"0009","recipient_name":"Client Corp SARL","status":"submitted","error_message":null,"metadata":{},"submitted_at":"2026-06-24T12:10:00.000Z","delivered_at":null,"created_at":"2026-06-24T12:10:00.000Z","updated_at":"2026-06-24T12:10:00.000Z","ubl_xml":"<?xml version=\"1.0\" encoding=\"UTF-8\"?><Invoice />"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/e-invoicing/submissions/:id/retry":{"post":{"operationId":"retryEInvoicingSubmission","summary":"Retry failed submission (deprecated path)","deprecated":true,"security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Retried submission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSubmission"},"example":{"id":"einv_sub_1234567890","entity_id":"ent_1234567890","environment":"sandbox","document_id":"inv_1234567890","document_type":"invoice","transmission_id":"msg_1234567890","recipient_peppol_id":"98765432109876","recipient_scheme_id":"0009","recipient_name":"Client Corp SARL","status":"submitted","error_message":null,"metadata":{},"submitted_at":"2026-06-24T12:10:00.000Z","delivered_at":null,"created_at":"2026-06-24T12:10:00.000Z","updated_at":"2026-06-24T12:10:00.000Z"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company-registry/search":{"get":{"operationId":"searchCompanyRegistry","summary":"Search company registry","description":"Search public company registries for autocomplete. Returns matching companies from government data sources like AJPES (Slovenia). Use this to auto-fill customer details when creating invoices.","security":[{"Bearer":[]}],"tags":["Company Registry"],"parameters":[{"schema":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code to search in (e.g., SI, AT, HR)","example":"SI"},"required":true,"description":"ISO 3166-1 alpha-2 country code to search in (e.g., SI, AT, HR)","name":"country_code","in":"query"},{"schema":{"type":"string","minLength":2,"description":"Search query - company name or tax number (min 2 characters)","example":"Primer"},"required":true,"description":"Search query - company name or tax number (min 2 characters)","name":"q","in":"query"},{"schema":{"type":"string","description":"Maximum number of results (default: 10, max: 50)","example":"10"},"required":false,"description":"Maximum number of results (default: 10, max: 50)","name":"limit","in":"query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyRegistrySearchResponse"},"examples":{"SlovenianCompany":{"value":{"data":[{"id":"creg_abc123def456","country_code":"SI","registration_number":"1234567","tax_number":"12345678","name":"Nebula Systems d.o.o.","address":"Slovenska cesta 1","post_code":"1000","city":"Ljubljana","legal_form":"d.o.o.","bank_accounts":[{"iban":"SI56 0201 0001 1234 567","bank":"NLB","is_active":true}],"status":"active"}]},"description":"Search results for Slovenian companies"},"MultipleResults":{"value":{"data":[{"id":"creg_abc123def456","country_code":"SI","registration_number":"1234567","tax_number":"12345678","name":"Nebula Systems d.o.o.","address":"Slovenska cesta 1","post_code":"1000","city":"Ljubljana","legal_form":"d.o.o.","bank_accounts":[],"status":"active"},{"id":"creg_xyz789ghi012","country_code":"SI","registration_number":"7654321","tax_number":"87654321","name":"Orbitna storitev s.p.","address":"Trubarjeva 5","post_code":"2000","city":"Maribor","legal_form":"s.p.","bank_accounts":[{"iban":"SI56 0510 0801 2345 678","bank":"NKBM","is_active":true}],"status":"active"}]},"description":"Multiple search results"},"EmptyResults":{"value":{"data":[]},"description":"No companies found matching the search query"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company-registry/countries":{"get":{"operationId":"getSupportedCountries","summary":"Get supported countries","description":"Returns a list of country codes for which company registry data is available. Use this to conditionally show the company autocomplete feature based on entity's country.","security":[{"Bearer":[]}],"tags":["Company Registry"],"responses":{"200":{"description":"List of supported country codes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportedCountriesResponse"},"examples":{"Success":{"value":{"data":["SI"]},"description":"List of country codes with registry data available"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/currency/exchange-rate":{"get":{"operationId":"getExchangeRate","summary":"Look up an exchange rate","description":"Returns the exchange rate from `from` to `to` for a given date. Results are cached to limit external lookups. Use this to prefill conversion rates on foreign-currency documents.","security":[{"Bearer":[]}],"tags":["Currency"],"parameters":[{"schema":{"type":"string","minLength":3,"maxLength":3,"description":"Source currency (ISO 4217). The document/expense currency.","example":"USD"},"required":true,"description":"Source currency (ISO 4217). The document/expense currency.","name":"from","in":"query"},{"schema":{"type":"string","minLength":3,"maxLength":3,"description":"Target/quote currency (ISO 4217). Usually the entity's base currency.","example":"EUR"},"required":true,"description":"Target/quote currency (ISO 4217). Usually the entity's base currency.","name":"to","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Rate date (YYYY-MM-DD). Uses the closest available historical rate when needed.","example":"2026-07-09"},"required":true,"description":"Rate date (YYYY-MM-DD). Uses the closest available historical rate when needed.","name":"date","in":"query"}],"responses":{"200":{"description":"Exchange rate lookup result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ExchangeRateLookup"}},"required":["data"]},"examples":{"UsdToEur":{"value":{"data":{"rate":0.92,"source":"auto","date":"2026-07-09T00:00:00.000Z","from_currency":"USD","to_currency":"EUR","available":true}}},"SameCurrency":{"value":{"data":{"rate":1,"source":null,"date":"2026-07-09T00:00:00.000Z","from_currency":"EUR","to_currency":"EUR","available":true}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tax-rate-estimates/us":{"get":{"operationId":"listUsTaxRateEstimates","summary":"List US tax rate estimates","description":"Returns the latest imported ZIP-level US tax-rate estimates for the active US entity. Results are informational helper data only; the API does not calculate document tax automatically.","security":[{"Bearer":[]}],"tags":["Tax Rate Estimates"],"parameters":[{"schema":{"type":"string","pattern":"^\\d{5}$","description":"US ZIP code to look up.","example":"90210"},"required":true,"description":"US ZIP code to look up.","name":"zip_code","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2,"description":"Optional two-letter US state filter.","example":"CA"},"required":false,"description":"Optional two-letter US state filter.","name":"state","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of US tax rate estimates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxRateEstimate"}}},"required":["data"]},"examples":{"CaliforniaZip":{"value":{"data":[{"id":"tre_123","country_code":"US","state":"CA","zip_code":"90210","tax_region_name":"Beverly Hills","estimated_combined_rate":0.095,"state_rate":0.06,"county_rate":0.01,"city_rate":0.015,"special_rate":0.01,"risk_level":1,"source":"avalara_zip5","source_month":"2026-05","imported_at":"2026-05-01T00:00:00.000Z"}]},"description":"Informational ZIP-level estimate for a US entity. The API does not apply this rate automatically."},"NoEstimateFound":{"value":{"data":[]},"description":"No estimate is available for the requested ZIP/state combination."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recurring-invoices":{"post":{"operationId":"createRecurringInvoice","summary":"Create a recurring invoice","description":"Create a new recurring invoice schedule.\nLink an existing invoice as the template and configure the generation frequency.\nThe source invoice's data (items, customer, notes) is used when generating new invoices.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Recurring Invoices"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Create Recurring Invoice Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"document_id":{"type":"string","maxLength":36},"name":{"type":"string","minLength":1},"frequency":{"type":"string","enum":["daily","weekly","monthly","yearly"]},"interval":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"day_of_week":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"day_of_month":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"month_of_year":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Start date in YYYY-MM-DD format","example":"2025-01-01"},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"End date in YYYY-MM-DD format (null = no end)","example":"2025-12-31"},"auto_send":{"type":"boolean"},"create_as_draft":{"type":"boolean"},"send_to":{"type":["string","null"],"maxLength":255},"payment_terms_days":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"notify_owner":{"type":"boolean"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"required":["document_id","name","frequency","start_date"],"additionalProperties":false},"examples":{"Monthly":{"value":{"document_id":"inv_6595a27b5d35015c3ef0c3fd","name":"Monthly telemetry hosting for Horizon","frequency":"monthly","day_of_month":1,"start_date":"2025-02-01"},"description":"Monthly recurring invoice on the 1st"},"Weekly":{"value":{"document_id":"inv_6595a27b5d35015c3ef0c3fd","name":"Weekly facility maintenance","frequency":"weekly","day_of_week":1,"start_date":"2025-02-03","end_date":"2025-12-31","auto_send":true},"description":"Weekly recurring invoice on Monday with auto-send"},"Monthly draft review":{"value":{"document_id":"inv_6595a27b5d35015c3ef0c3fd","name":"Monthly mission planning retainer draft","frequency":"monthly","day_of_month":15,"start_date":"2025-02-15","create_as_draft":true,"notify_owner":true},"description":"Generate each recurring invoice as a draft so a user can review it before sending."},"Auto-send to billing inbox":{"value":{"document_id":"inv_6595a27b5d35015c3ef0c3fd","name":"Monthly telemetry hosting with delivery","frequency":"monthly","day_of_month":1,"start_date":"2025-02-01","auto_send":true,"send_to":"ap@example.com","payment_terms_days":14},"description":"Generate and send invoices automatically to a fixed recipient with custom payment terms."}}}}},"responses":{"201":{"description":"Created recurring invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringInvoice"},"examples":{"Monthly":{"value":{"id":"rinv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","document_id":"inv_6595a27b5d35015c3ef0c3fd","name":"Monthly telemetry hosting for Horizon","frequency":"monthly","interval":1,"day_of_week":null,"day_of_month":1,"month_of_year":null,"start_date":"2025-02-01","end_date":null,"next_run_date":"2025-02-01","last_run_date":null,"status":"active","auto_send":false,"create_as_draft":false,"send_to":null,"payment_terms_days":null,"notify_owner":true,"invoices_generated":0,"last_generated_invoice_id":null,"last_error":null,"last_error_at":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z","deleted_at":null},"description":"Created monthly recurring invoice"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getRecurringInvoices","summary":"List all recurring invoices","description":"Retrieve a paginated list of recurring invoice schedules with optional filtering and sorting.\nSupports cursor-based pagination, flexible JSON querying with MongoDB-style operators, full-text search, and sorting.","security":[{"Bearer":[]}],"tags":["Recurring Invoices"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","name","status","next_run_date","created_at","-id","-name","-status","-next_run_date","-created_at"]},{"type":"array","items":{"type":"string","enum":["id","name","status","next_run_date","created_at","-id","-name","-status","-next_run_date","-created_at"]}}],"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, name, status, frequency, document_id\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, name, status, frequency, document_id\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"type":"string","description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","example":"Acme Corporation"},"required":false,"description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","name":"search","in":"query"},{"schema":{"type":"boolean","description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items."},"required":false,"description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.","name":"deleted","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of recurring invoices","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RecurringInvoice"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"rinv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","document_id":"inv_6595a27b5d35015c3ef0c3fd","name":"Monthly telemetry hosting for Horizon","frequency":"monthly","interval":1,"day_of_week":null,"day_of_month":1,"month_of_year":null,"start_date":"2025-02-01","end_date":null,"next_run_date":"2025-02-01","last_run_date":null,"status":"active","auto_send":false,"create_as_draft":false,"send_to":null,"payment_terms_days":null,"notify_owner":true,"invoices_generated":0,"last_generated_invoice_id":null,"last_error":null,"last_error_at":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z","deleted_at":null}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of recurring invoices"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recurring-invoices/{id}":{"get":{"operationId":"getRecurringInvoiceById","summary":"Get recurring invoice by ID","description":"Retrieve a single recurring invoice schedule by its unique identifier.","security":[{"Bearer":[]}],"tags":["Recurring Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Recurring invoice instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringInvoice"},"examples":{"200":{"value":{"id":"rinv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","document_id":"inv_6595a27b5d35015c3ef0c3fd","name":"Monthly telemetry hosting for Horizon","frequency":"monthly","interval":1,"day_of_week":null,"day_of_month":1,"month_of_year":null,"start_date":"2025-02-01","end_date":null,"next_run_date":"2025-02-01","last_run_date":null,"status":"active","auto_send":false,"create_as_draft":false,"send_to":null,"payment_terms_days":null,"notify_owner":true,"invoices_generated":0,"last_generated_invoice_id":null,"last_error":null,"last_error_at":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z","deleted_at":null},"description":"Created monthly recurring invoice"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateRecurringInvoice","summary":"Update a recurring invoice","description":"Update an existing recurring invoice schedule.\nOnly the provided fields will be updated.\nSchedule changes automatically recalculate the next run date.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Recurring Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Recurring Invoice Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":255},"frequency":{"type":"string","enum":["daily","weekly","monthly","yearly"]},"interval":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"day_of_week":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"day_of_month":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"month_of_year":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"auto_send":{"type":"boolean"},"create_as_draft":{"type":"boolean"},"send_to":{"type":["string","null"],"maxLength":255},"payment_terms_days":{"type":["integer","null"],"minimum":-2147483648,"maximum":2147483647},"notify_owner":{"type":"boolean"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"additionalProperties":false},"examples":{"Update name":{"value":{"name":"Monthly telemetry hosting for Horizon Launch"},"description":"Update recurring invoice name"},"Pause schedule":{"value":{"end_date":"2025-12-31"},"description":"Set or change the end date. Use POST /recurring-invoices/{id}/pause to pause generation immediately."},"Change delivery settings":{"value":{"auto_send":true,"notify_owner":false,"send_to":"ap@example.com"},"description":"Enable auto-send and disable owner notifications for this schedule."}}}}},"responses":{"200":{"description":"Updated recurring invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringInvoice"},"examples":{"Updated":{"value":{"id":"rinv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","document_id":"inv_6595a27b5d35015c3ef0c3fd","name":"Monthly telemetry hosting for Horizon","frequency":"monthly","interval":1,"day_of_week":null,"day_of_month":1,"month_of_year":null,"start_date":"2025-02-01","end_date":null,"next_run_date":"2025-02-01","last_run_date":null,"status":"active","auto_send":false,"create_as_draft":false,"send_to":null,"payment_terms_days":null,"notify_owner":true,"invoices_generated":0,"last_generated_invoice_id":null,"last_error":null,"last_error_at":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z","deleted_at":null},"description":"Created monthly recurring invoice"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteRecurringInvoice","summary":"Delete a recurring invoice","description":"Soft delete a recurring invoice schedule. The schedule is moved to the trash and can be restored.","security":[{"Bearer":[]}],"tags":["Recurring Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Recurring invoice deleted successfully"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recurring-invoices/{id}/restore":{"post":{"operationId":"restoreRecurringInvoice","summary":"Restore a deleted recurring invoice","description":"Restore a soft-deleted recurring invoice schedule from the trash.","security":[{"Bearer":[]}],"tags":["Recurring Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Restored recurring invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringInvoice"},"examples":{"200":{"value":{"id":"rinv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","document_id":"inv_6595a27b5d35015c3ef0c3fd","name":"Monthly telemetry hosting for Horizon","frequency":"monthly","interval":1,"day_of_week":null,"day_of_month":1,"month_of_year":null,"start_date":"2025-02-01","end_date":null,"next_run_date":"2025-02-01","last_run_date":null,"status":"active","auto_send":false,"create_as_draft":false,"send_to":null,"payment_terms_days":null,"notify_owner":true,"invoices_generated":0,"last_generated_invoice_id":null,"last_error":null,"last_error_at":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z","deleted_at":null},"description":"Created monthly recurring invoice"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recurring-invoices/{id}/permanent":{"delete":{"operationId":"permanentDeleteRecurringInvoice","summary":"Permanently delete a recurring invoice","description":"Permanently delete a soft-deleted recurring invoice schedule. Only schedules in the trash can be permanently deleted.","security":[{"Bearer":[]}],"tags":["Recurring Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Recurring invoice permanently deleted"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recurring-invoices/{id}/pause":{"post":{"operationId":"pauseRecurringInvoice","summary":"Pause a recurring invoice","description":"Pause an active recurring invoice schedule. No invoices will be generated while paused. The next run date is cleared.","security":[{"Bearer":[]}],"tags":["Recurring Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Paused recurring invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringInvoice"},"examples":{"200":{"value":{"id":"rinv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","document_id":"inv_6595a27b5d35015c3ef0c3fd","name":"Monthly telemetry hosting for Horizon","frequency":"monthly","interval":1,"day_of_week":null,"day_of_month":1,"month_of_year":null,"start_date":"2025-02-01","end_date":null,"next_run_date":"2025-02-01","last_run_date":null,"status":"active","auto_send":false,"create_as_draft":false,"send_to":null,"payment_terms_days":null,"notify_owner":true,"invoices_generated":0,"last_generated_invoice_id":null,"last_error":null,"last_error_at":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z","deleted_at":null},"description":"Created monthly recurring invoice"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recurring-invoices/{id}/resume":{"post":{"operationId":"resumeRecurringInvoice","summary":"Resume a paused recurring invoice","description":"Resume a paused recurring invoice schedule. The next run date is recalculated from the current date.","security":[{"Bearer":[]}],"tags":["Recurring Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Resumed recurring invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringInvoice"},"examples":{"200":{"value":{"id":"rinv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","document_id":"inv_6595a27b5d35015c3ef0c3fd","name":"Monthly telemetry hosting for Horizon","frequency":"monthly","interval":1,"day_of_week":null,"day_of_month":1,"month_of_year":null,"start_date":"2025-02-01","end_date":null,"next_run_date":"2025-02-01","last_run_date":null,"status":"active","auto_send":false,"create_as_draft":false,"send_to":null,"payment_terms_days":null,"notify_owner":true,"invoices_generated":0,"last_generated_invoice_id":null,"last_error":null,"last_error_at":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z","deleted_at":null},"description":"Created monthly recurring invoice"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/recurring-invoices/{id}/trigger":{"post":{"operationId":"triggerRecurringInvoice","summary":"Manually trigger invoice generation","description":"Manually trigger invoice generation for a recurring invoice schedule. Creates a new invoice for every call by default. Supply a stable X-Request-Id to safely retry the same intentional trigger without creating another invoice.","security":[{"Bearer":[]}],"tags":["Recurring Invoices"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"},{"name":"X-Request-Id","in":"header","required":false,"description":"Stable identifier for retrying the same intentional recurring-invoice trigger without creating another invoice. A concurrent retry while the first trigger is still processing returns `409 conflict`. See the [idempotency guide](https://docs.spaceinvoices.com/guides/idempotency/).","schema":{"type":"string","maxLength":100,"example":"order_123:create_invoice"}}],"responses":{"200":{"description":"Recurring invoice after triggering generation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringInvoice"},"examples":{"200":{"value":{"id":"rinv_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","document_id":"inv_6595a27b5d35015c3ef0c3fd","name":"Monthly telemetry hosting for Horizon","frequency":"monthly","interval":1,"day_of_week":null,"day_of_month":1,"month_of_year":null,"start_date":"2025-02-01","end_date":null,"next_run_date":"2025-02-01","last_run_date":null,"status":"active","auto_send":false,"create_as_draft":false,"send_to":null,"payment_terms_days":null,"notify_owner":true,"invoices_generated":0,"last_generated_invoice_id":null,"last_error":null,"last_error_at":null,"metadata":{},"created_at":"2025-01-15T00:00:00.000Z","updated_at":"2025-01-15T00:00:00.000Z","deleted_at":null},"description":"Created monthly recurring invoice"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A trigger with the same request ID is already being processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/revenue-recognition/settings":{"get":{"operationId":"getRevenueRecognitionSettings","summary":"Get revenue recognition settings","security":[{"Bearer":[]}],"tags":["Revenue Recognition"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Revenue recognition settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevenueRecognitionSettingsResponse"},"example":{"default_method":"service_period_daily"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateRevenueRecognitionSettings","summary":"Update revenue recognition settings","security":[{"Bearer":[]}],"tags":["Revenue Recognition"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update revenue recognition settings","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRevenueRecognitionSettings"},"examples":{"UseServicePeriodDaily":{"value":{"default_method":"service_period_daily"},"description":"Generate recognition entries from item/document service periods when finalized documents are created or changed."},"DisableGeneratedRecognition":{"value":{"default_method":null},"description":"Disable generated recognition schedules. Reports fall back to finalized document-date revenue for recognized revenue."}}}}},"responses":{"200":{"description":"Updated revenue recognition settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevenueRecognitionSettingsResponse"},"example":{"default_method":"service_period_daily"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/revenue-recognition/backfill":{"post":{"operationId":"backfillRevenueRecognition","summary":"Backfill generated revenue recognition entries","security":[{"Bearer":[]}],"tags":["Revenue Recognition"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Backfill revenue recognition entries","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date_from":{"type":["string","null"],"description":"Optional document issue date lower bound in YYYY-MM-DD format.","example":"2026-01-01"},"date_to":{"type":["string","null"],"description":"Optional document issue date upper bound in YYYY-MM-DD format.","example":"2026-12-31"},"dry_run":{"type":"boolean","default":false,"description":"When true, counts eligible documents without writing entries.","example":false}},"additionalProperties":false},"examples":{"DryRun":{"value":{"date_from":"2026-01-01","date_to":"2026-03-31","dry_run":true},"description":"Preview how many finalized documents would be processed before generating entries."},"GenerateEntries":{"value":{"date_from":"2026-01-01","date_to":"2026-03-31","dry_run":false},"description":"Generate recognition entries for eligible finalized documents in the selected period."}}}}},"responses":{"200":{"description":"Backfill result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevenueRecognitionBackfillResponse"},"example":{"processed_documents":12,"generated_entries":36,"dry_run":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/revenue-recognition/report":{"get":{"operationId":"getRevenueRecognitionReport","summary":"Get revenue recognition report","security":[{"Bearer":[]}],"tags":["Revenue Recognition"],"parameters":[{"schema":{"type":"string","description":"Report start date in YYYY-MM-DD format.","example":"2026-01-01"},"required":true,"description":"Report start date in YYYY-MM-DD format.","name":"date_from","in":"query"},{"schema":{"type":"string","description":"Report end date in YYYY-MM-DD format.","example":"2026-12-31"},"required":true,"description":"Report end date in YYYY-MM-DD format.","name":"date_to","in":"query"},{"schema":{"type":"string","enum":["recognized","deferred"],"default":"recognized","description":"recognized returns revenue recognized inside each period. deferred returns the remaining future recognition balance at the end of each period.","example":"recognized"},"required":false,"description":"recognized returns revenue recognized inside each period. deferred returns the remaining future recognition balance at the end of each period.","name":"basis","in":"query"},{"schema":{"type":"string","enum":["financial_category"],"default":"financial_category","description":"Report grouping dimension.","example":"financial_category"},"required":false,"description":"Report grouping dimension.","name":"group_by","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Revenue recognition report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevenueRecognitionReportResponse"},"examples":{"RecognizedByCategory":{"value":{"basis":"recognized","group_by":"financial_category","calculation_mode":"recognition_entries","periods":[{"period":"2026-01","date_from":"2026-01-01","date_to":"2026-01-31"},{"period":"2026-02","date_from":"2026-02-01","date_to":"2026-02-28"}],"series":[{"key":"fcat_hosting","financial_category_id":"fcat_hosting","name":"Hosting revenue","color":"#2563eb","values":[2500,2500],"total":5000}],"totals":[2500,2500],"total":5000,"currency_code":"EUR","date_from":"2026-01-01","date_to":"2026-02-28"},"description":"Recognized revenue grouped by financial category using generated recognition entries."},"DeferredMonthly":{"value":{"basis":"deferred","group_by":"financial_category","calculation_mode":"recognition_entries","periods":[{"period":"2026-01","date_from":"2026-01-01","date_to":"2026-01-31"},{"period":"2026-02","date_from":"2026-02-01","date_to":"2026-02-28"}],"series":[{"key":"deferred","financial_category_id":null,"name":"Deferred revenue","color":null,"values":[5000,2500],"total":7500}],"totals":[5000,2500],"total":7500,"currency_code":"EUR","date_from":"2026-01-01","date_to":"2026-02-28"},"description":"Deferred revenue report for obligations not yet recognized."},"DocumentDateFallback":{"value":{"basis":"recognized","group_by":"financial_category","calculation_mode":"document_date_fallback","periods":[{"period":"2026-01","date_from":"2026-01-01","date_to":"2026-01-31"},{"period":"2026-02","date_from":"2026-02-01","date_to":"2026-02-28"}],"series":[{"key":"uncategorized","financial_category_id":null,"name":"Uncategorized","color":null,"values":[1200,800],"total":2000}],"totals":[1200,800],"total":2000,"currency_code":"EUR","date_from":"2026-01-01","date_to":"2026-02-28"},"description":"Recognized revenue fallback when generated recognition automation is disabled or no generated entries exist."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/revenue-recognition/details":{"get":{"operationId":"getRevenueRecognitionDetails","summary":"Get revenue recognition report details","security":[{"Bearer":[]}],"tags":["Revenue Recognition"],"parameters":[{"schema":{"type":"string","description":"Report start date in YYYY-MM-DD format.","example":"2026-01-01"},"required":true,"description":"Report start date in YYYY-MM-DD format.","name":"date_from","in":"query"},{"schema":{"type":"string","description":"Report end date in YYYY-MM-DD format.","example":"2026-12-31"},"required":true,"description":"Report end date in YYYY-MM-DD format.","name":"date_to","in":"query"},{"schema":{"type":"string","enum":["recognized","deferred"],"default":"recognized","description":"recognized returns revenue recognized inside each period. deferred returns the remaining future recognition balance at the end of each period.","example":"recognized"},"required":false,"description":"recognized returns revenue recognized inside each period. deferred returns the remaining future recognition balance at the end of each period.","name":"basis","in":"query"},{"schema":{"type":"string","enum":["financial_category"],"default":"financial_category","description":"Report grouping dimension.","example":"financial_category"},"required":false,"description":"Report grouping dimension.","name":"group_by","in":"query"},{"schema":{"type":["string","null"],"description":"Optional category ID. Use null/omit for all categories.","example":"fcat_abc123"},"required":false,"description":"Optional category ID. Use null/omit for all categories.","name":"financial_category_id","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Revenue recognition details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevenueRecognitionDetailsResponse"},"examples":{"ServicePeriodLine":{"value":{"calculation_mode":"recognition_entries","data":[{"id":"rre_123","document_id":"inv_123","document_type":"invoice","document_number":"2026-00001","document_date":"2026-01-15","document_item_id":"di_123","customer_id":"cus_123","customer_name":"Acme Inc.","financial_category_id":"fcat_hosting","financial_category_name":"Hosting revenue","currency_code":"EUR","source_amount":5000,"recognized_amount":2500,"period_start":"2026-01-01","period_end":"2026-01-31","service_period_start":"2026-01-01","service_period_end":"2026-02-28","method":"service_period_daily"}],"total":2500,"currency_code":"EUR"},"description":"Line-level recognition detail created from a document item service period."},"DocumentDateFallback":{"value":{"calculation_mode":"document_date_fallback","data":[{"id":"inv_123:item_123:2026-01","document_id":"inv_123","document_type":"invoice","document_number":"2026-00001","document_date":"2026-01-15","document_item_id":"di_123","customer_id":"cus_123","customer_name":"Acme Inc.","financial_category_id":null,"financial_category_name":"Uncategorized","currency_code":"EUR","source_amount":1200,"recognized_amount":1200,"period_start":"2026-01-01","period_end":"2026-01-31","service_period_start":"2026-01-15","service_period_end":"2026-01-15","method":"document_date_fallback"}],"total":1200,"currency_code":"EUR"},"description":"Detail output when reports use finalized document dates instead of generated schedules."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment-reminders/send":{"post":{"operationId":"sendPaymentReminder","summary":"Send payment reminder","description":"Send one manual payment reminder email for all overdue unpaid invoices belonging to the selected customer in the active entity.","security":[{"Bearer":[]}],"tags":["Payment Reminders"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendPaymentReminderBody"},"examples":{"Default":{"value":{"customer_id":"cust_123","language":"en-US"}},"EditedContent":{"value":{"customer_id":"cust_123","recipient_email":"customer@example.com","subject":"Reminder for {overdue_count} overdue invoices","body_text":"Please review these overdue invoices:\n{invoice_list}\n\n{payment_instructions}","payment_instructions":"Please remit payment to IBAN {iban}.","language":"en-US"}}}}}},"responses":{"200":{"description":"Payment reminder sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendPaymentReminderResponse"},"examples":{"Success":{"value":{"message_id":"msg_123","status":"sent","to":"customer@example.com","subject":"Reminder for 2 overdue invoices","overdue_invoice_count":2,"invoice_ids":["inv_123","inv_456"]}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tax-reports/kir":{"post":{"operationId":"generateKirExport","summary":"Generate KIR export (Issued Invoices Ledger)","description":"\nGenerate a KIR (Knjiga izdanih računov / Evidenca obračunanega DDV) export file for FURS.\n\nThis export contains all issued invoices and credit notes for the specified period in FURS-compliant XML format,\npackaged in a ZIP archive ready for upload to eDavki.\n\n**Period Selection:**\n- Use `month` for monthly exports (e.g., month=1 for January)\n- Use `quarter` for quarterly exports (e.g., quarter=1 for Q1)\n- Cannot use both month and quarter\n\n**Transaction Type Mapping:**\n- Domestic sales → P7 (taxable supplies) + P14/P15/P16 (VAT by rate)\n- Intra-EU B2B → P10 (reverse charge)\n- Intra-EU B2C → P7 + P14/P15/P16 (standard VAT)\n- Export (third country) → P27 (export exemption)\n\n**Credit Notes:**\n- Included with negative amounts as per FURS specification\n- Same field mapping as invoices, but amounts are negated\n\n**Important:**\n- Voided documents are included with zero amounts\n- Entity must have a valid Slovenian tax number (SI prefix is automatically removed)\n","security":[{"Bearer":[]}],"tags":["Tax Reports"],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}$","description":"Year for KIR export (e.g., 2025)","example":"2025"},"required":true,"description":"Year for KIR export (e.g., 2025)","name":"year","in":"query"},{"schema":{"type":"string","pattern":"^(1[0-2]|[1-9])$","description":"Month for monthly export (1-12). Cannot be used with quarter.","example":"1"},"required":false,"description":"Month for monthly export (1-12). Cannot be used with quarter.","name":"month","in":"query"},{"schema":{"type":"string","pattern":"^[1-4]$","description":"Quarter for quarterly export (1-4). Cannot be used with month.","example":"1"},"required":false,"description":"Quarter for quarterly export (1-4). Cannot be used with month.","name":"quarter","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"KIR export ZIP file containing FURS-compliant XML","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tax-reports/si/profile":{"get":{"operationId":"getSloveniaTaxProfile","summary":"Get Slovenia yearly tax profile","description":"Retrieve the normalized Slovenia-specific tax profile stored on the entity, including inferred business form and yearly-export support status.","security":[{"Bearer":[]}],"tags":["Tax Reports"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Normalized Slovenia tax profile for the entity","content":{"application/json":{"schema":{"type":"object","properties":{"business_form":{"type":["string","null"],"enum":["sp","doo","dno","club",null],"description":"Canonical Slovenian legal form for the entity.","example":"sp"},"income_tax_regime":{"type":["string","null"],"enum":["normirani","dejanski",null],"description":"Income tax regime used by the Slovenian entity.","example":"normirani"},"vat_profile":{"type":["string","null"],"enum":["standard","special_vat_identified","non_vat_subject",null],"description":"Slovenia-specific VAT subject subtype.","example":"standard"},"tax_residency":{"type":["string","null"],"enum":["resident","non_resident",null],"description":"Tax residency status for Slovenian yearly reporting.","example":"resident"},"yearly_reporting":{"type":"object","properties":{"activity_codes":{"type":"array","items":{"type":"string","pattern":"^\\d{2}\\.\\d{3}$","description":"Slovenian SKD activity code used for yearly reporting.","example":"62.010"},"description":"Ordered SKD activity codes.","example":["62.010","47.910"]},"registration_number":{"type":["string","null"],"description":"Optional registration number used in the filing.","example":"1234567"},"accounting_type":{"type":["string","null"],"enum":["records","single_entry","double_entry",null],"description":"Accounting / records mode used in the filing.","example":"records"},"normiranec_insurance_basis":{"type":["string","null"],"enum":["full_time_self_employed","other",null],"description":"Insurance basis used by normirani rules.","example":"full_time_self_employed"},"default_withholding_tax_amount":{"type":["number","null"],"minimum":0,"description":"Persisted default withholding tax amount for yearly reviews.","example":0},"default_foreign_tax_credit_amount":{"type":["number","null"],"minimum":0,"description":"Persisted default foreign tax credit amount for yearly reviews.","example":0}},"required":["activity_codes","registration_number","accounting_type","normiranec_insurance_basis","default_withholding_tax_amount","default_foreign_tax_credit_amount"]},"accounting_exports":{"type":"object","properties":{"preferred_format":{"type":["string","null"],"enum":["vod_xml","vasco_xml","minimax_xml",null],"description":"Preferred Slovenian accounting export format.","example":"vod_xml"},"konto_mappings":{"allOf":[{"$ref":"#/components/schemas/SloveniaAccountingKontoMappings"},{"description":"Normalized semantic konto mappings shared by Slovenian accounting exports."}]}},"required":["preferred_format","konto_mappings"]},"business_form_source":{"type":"string","enum":["stored","registry","unknown"]},"inferred_business_form":{"type":["string","null"],"enum":["sp","doo","dno","club",null],"description":"Canonical Slovenian legal form for the entity.","example":"sp"},"supported_exports":{"type":"object","properties":{"yearly_normirani":{"type":"boolean"},"vod_xml":{"type":"boolean"},"vasco_xml":{"type":"boolean"},"minimax_xml":{"type":"boolean"}},"required":["yearly_normirani","vod_xml","vasco_xml","minimax_xml"]},"unsupported_reason":{"type":["string","null"]}},"required":["business_form","income_tax_regime","vat_profile","tax_residency","yearly_reporting","accounting_exports","business_form_source","inferred_business_form","supported_exports","unsupported_reason"]},"example":{"business_form":"sp","income_tax_regime":"normirani","vat_profile":"standard","tax_residency":"resident","yearly_reporting":{"activity_codes":["62.010","47.910"],"registration_number":"1234567","accounting_type":"records","normiranec_insurance_basis":"full_time_self_employed","default_withholding_tax_amount":0,"default_foreign_tax_credit_amount":0},"accounting_exports":{"preferred_format":"vod_xml","konto_mappings":{"receivables":"1200","payables":"2200","sales_vat_22":"26000","sales_vat_95":"26001","sales_vat_5":"26002","purchase_vat_recoverable_22":"16000","purchase_vat_recoverable_95":"16001","purchase_vat_recoverable_5":"16002","sales_revenue_22":"7600","sales_revenue_95":"7601","sales_revenue_5":"7602","sales_revenue_exempt":"7680","sales_revenue_eu_goods":"7600","sales_revenue_eu_services":"7601","sales_revenue_reverse_charge":"7600","sales_revenue_third_country_goods":"7600","sales_revenue_third_country_services":"7680","purchase_expense_22":"4000","purchase_expense_95":"4001","purchase_expense_5":"4002","purchase_expense_exempt":"4680","purchase_expense_eu_goods":"4000","purchase_expense_eu_services":"4680","purchase_expense_reverse_charge":"4000","purchase_expense_third_country_goods":"4000","purchase_expense_third_country_services":"4680"}},"business_form_source":"stored","inferred_business_form":"sp","supported_exports":{"yearly_normirani":true,"vod_xml":true,"vasco_xml":false,"minimax_xml":false},"unsupported_reason":null}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"updateSloveniaTaxProfile","summary":"Update Slovenia yearly tax profile","description":"Update the Slovenia-specific tax profile stored on the entity. Unsupported profiles are stored for future use but remain blocked for yearly export.","security":[{"Bearer":[]}],"tags":["Tax Reports"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Slovenia tax profile patch","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"business_form":{"type":["string","null"],"enum":["sp","doo","dno","club",null],"description":"Canonical Slovenian legal form for the entity.","example":"sp"},"income_tax_regime":{"type":["string","null"],"enum":["normirani","dejanski",null],"description":"Income tax regime used by the Slovenian entity.","example":"normirani"},"vat_profile":{"type":["string","null"],"enum":["standard","special_vat_identified","non_vat_subject",null],"description":"Slovenia-specific VAT subject subtype.","example":"standard"},"tax_residency":{"type":["string","null"],"enum":["resident","non_resident",null],"description":"Tax residency status for Slovenian yearly reporting.","example":"resident"},"yearly_reporting":{"type":["object","null"],"properties":{"activity_codes":{"type":["array","null"],"items":{"type":"string","pattern":"^\\d{2}\\.\\d{3}$","description":"Slovenian SKD activity code used for yearly reporting.","example":"62.010"}},"registration_number":{"type":["string","null"]},"accounting_type":{"type":["string","null"],"enum":["records","single_entry","double_entry",null],"description":"Accounting or records mode used for the yearly filing.","example":"records"},"normiranec_insurance_basis":{"type":["string","null"],"enum":["full_time_self_employed","other",null],"description":"Insurance basis used to determine the applicable normirani rules.","example":"full_time_self_employed"},"default_withholding_tax_amount":{"type":["number","null"],"minimum":0,"description":"Monetary amount in EUR.","example":0},"default_foreign_tax_credit_amount":{"type":["number","null"],"minimum":0,"description":"Monetary amount in EUR.","example":0}}},"accounting_exports":{"type":["object","null"],"properties":{"preferred_format":{"type":["string","null"],"enum":["vod_xml","vasco_xml","minimax_xml",null],"description":"Stored preferred export format for Slovenian accounting handoff.","example":"vod_xml"},"konto_mappings":{"type":["object","null"],"properties":{"receivables":{"type":["string","null"],"maxLength":8},"payables":{"type":["string","null"],"maxLength":8},"sales_vat_22":{"type":["string","null"],"maxLength":8},"sales_vat_95":{"type":["string","null"],"maxLength":8},"sales_vat_5":{"type":["string","null"],"maxLength":8},"purchase_vat_recoverable_22":{"type":["string","null"],"maxLength":8},"purchase_vat_recoverable_95":{"type":["string","null"],"maxLength":8},"purchase_vat_recoverable_5":{"type":["string","null"],"maxLength":8},"sales_revenue_22":{"type":["string","null"],"maxLength":8},"sales_revenue_95":{"type":["string","null"],"maxLength":8},"sales_revenue_5":{"type":["string","null"],"maxLength":8},"sales_revenue_exempt":{"type":["string","null"],"maxLength":8},"sales_revenue_eu_goods":{"type":["string","null"],"maxLength":8},"sales_revenue_eu_services":{"type":["string","null"],"maxLength":8},"sales_revenue_reverse_charge":{"type":["string","null"],"maxLength":8},"sales_revenue_third_country_goods":{"type":["string","null"],"maxLength":8},"sales_revenue_third_country_services":{"type":["string","null"],"maxLength":8},"purchase_expense_22":{"type":["string","null"],"maxLength":8},"purchase_expense_95":{"type":["string","null"],"maxLength":8},"purchase_expense_5":{"type":["string","null"],"maxLength":8},"purchase_expense_exempt":{"type":["string","null"],"maxLength":8},"purchase_expense_eu_goods":{"type":["string","null"],"maxLength":8},"purchase_expense_eu_services":{"type":["string","null"],"maxLength":8},"purchase_expense_reverse_charge":{"type":["string","null"],"maxLength":8},"purchase_expense_third_country_goods":{"type":["string","null"],"maxLength":8},"purchase_expense_third_country_services":{"type":["string","null"],"maxLength":8}}}}}}},"examples":{"NormiraniSp":{"value":{"business_form":"sp","income_tax_regime":"normirani","tax_residency":"resident","yearly_reporting":{"activity_codes":["62.010","47.910"],"registration_number":"1234567","accounting_type":"records","normiranec_insurance_basis":"full_time_self_employed","default_withholding_tax_amount":0,"default_foreign_tax_credit_amount":0}},"description":"Supported resident normirani s.p. profile for yearly DDD-DDD export."},"NonVatSubject":{"value":{"business_form":"sp","income_tax_regime":"normirani","vat_profile":"non_vat_subject","tax_residency":"resident","yearly_reporting":{"activity_codes":["62.010"],"registration_number":"1234567","accounting_type":"records","normiranec_insurance_basis":"full_time_self_employed"}},"description":"Store a non-VAT-subject Slovenian profile without treating it as a UI-only alias."}}}}},"responses":{"200":{"description":"Updated normalized Slovenia tax profile","content":{"application/json":{"schema":{"type":"object","properties":{"business_form":{"type":["string","null"],"enum":["sp","doo","dno","club",null],"description":"Canonical Slovenian legal form for the entity.","example":"sp"},"income_tax_regime":{"type":["string","null"],"enum":["normirani","dejanski",null],"description":"Income tax regime used by the Slovenian entity.","example":"normirani"},"vat_profile":{"type":["string","null"],"enum":["standard","special_vat_identified","non_vat_subject",null],"description":"Slovenia-specific VAT subject subtype.","example":"standard"},"tax_residency":{"type":["string","null"],"enum":["resident","non_resident",null],"description":"Tax residency status for Slovenian yearly reporting.","example":"resident"},"yearly_reporting":{"type":"object","properties":{"activity_codes":{"type":"array","items":{"type":"string","pattern":"^\\d{2}\\.\\d{3}$","description":"Slovenian SKD activity code used for yearly reporting.","example":"62.010"},"description":"Ordered SKD activity codes.","example":["62.010","47.910"]},"registration_number":{"type":["string","null"],"description":"Optional registration number used in the filing.","example":"1234567"},"accounting_type":{"type":["string","null"],"enum":["records","single_entry","double_entry",null],"description":"Accounting / records mode used in the filing.","example":"records"},"normiranec_insurance_basis":{"type":["string","null"],"enum":["full_time_self_employed","other",null],"description":"Insurance basis used by normirani rules.","example":"full_time_self_employed"},"default_withholding_tax_amount":{"type":["number","null"],"minimum":0,"description":"Persisted default withholding tax amount for yearly reviews.","example":0},"default_foreign_tax_credit_amount":{"type":["number","null"],"minimum":0,"description":"Persisted default foreign tax credit amount for yearly reviews.","example":0}},"required":["activity_codes","registration_number","accounting_type","normiranec_insurance_basis","default_withholding_tax_amount","default_foreign_tax_credit_amount"]},"accounting_exports":{"type":"object","properties":{"preferred_format":{"type":["string","null"],"enum":["vod_xml","vasco_xml","minimax_xml",null],"description":"Preferred Slovenian accounting export format.","example":"vod_xml"},"konto_mappings":{"allOf":[{"$ref":"#/components/schemas/SloveniaAccountingKontoMappings"},{"description":"Normalized semantic konto mappings shared by Slovenian accounting exports."}]}},"required":["preferred_format","konto_mappings"]},"business_form_source":{"type":"string","enum":["stored","registry","unknown"]},"inferred_business_form":{"type":["string","null"],"enum":["sp","doo","dno","club",null],"description":"Canonical Slovenian legal form for the entity.","example":"sp"},"supported_exports":{"type":"object","properties":{"yearly_normirani":{"type":"boolean"},"vod_xml":{"type":"boolean"},"vasco_xml":{"type":"boolean"},"minimax_xml":{"type":"boolean"}},"required":["yearly_normirani","vod_xml","vasco_xml","minimax_xml"]},"unsupported_reason":{"type":["string","null"]}},"required":["business_form","income_tax_regime","vat_profile","tax_residency","yearly_reporting","accounting_exports","business_form_source","inferred_business_form","supported_exports","unsupported_reason"]},"example":{"business_form":"sp","income_tax_regime":"normirani","vat_profile":"standard","tax_residency":"resident","yearly_reporting":{"activity_codes":["62.010","47.910"],"registration_number":"1234567","accounting_type":"records","normiranec_insurance_basis":"full_time_self_employed","default_withholding_tax_amount":0,"default_foreign_tax_credit_amount":0},"accounting_exports":{"preferred_format":"vod_xml","konto_mappings":{"receivables":"1200","payables":"2200","sales_vat_22":"26000","sales_vat_95":"26001","sales_vat_5":"26002","purchase_vat_recoverable_22":"16000","purchase_vat_recoverable_95":"16001","purchase_vat_recoverable_5":"16002","sales_revenue_22":"7600","sales_revenue_95":"7601","sales_revenue_5":"7602","sales_revenue_exempt":"7680","sales_revenue_eu_goods":"7600","sales_revenue_eu_services":"7601","sales_revenue_reverse_charge":"7600","sales_revenue_third_country_goods":"7600","sales_revenue_third_country_services":"7680","purchase_expense_22":"4000","purchase_expense_95":"4001","purchase_expense_5":"4002","purchase_expense_exempt":"4680","purchase_expense_eu_goods":"4000","purchase_expense_eu_services":"4680","purchase_expense_reverse_charge":"4000","purchase_expense_third_country_goods":"4000","purchase_expense_third_country_services":"4680"}},"business_form_source":"stored","inferred_business_form":"sp","supported_exports":{"yearly_normirani":true,"vod_xml":true,"vasco_xml":false,"minimax_xml":false},"unsupported_reason":null}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tax-reports/si/yearly/normirani/review":{"post":{"operationId":"reviewSloveniaYearlyNormiraniReport","summary":"Review yearly Slovenia normirani filing","description":"Build a review draft for the yearly Slovenia DDD-DDD filing for the supported resident normirani s.p. path.","security":[{"Bearer":[]}],"tags":["Tax Reports"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Yearly review request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":2025,"maximum":2100,"description":"Tax year for the yearly Slovenia eDavki filing.","example":2025}},"required":["year"]},"examples":{"CurrentYear":{"value":{"year":2025},"description":"Compute automatic values and warnings for one yearly normirani filing period."}}}}},"responses":{"200":{"description":"Computed yearly review draft","content":{"application/json":{"schema":{"type":"object","properties":{"entity_id":{"type":"string"},"year":{"type":"integer","minimum":2025,"maximum":2100,"description":"Tax year for the yearly Slovenia eDavki filing.","example":2025},"filing_kind":{"type":"string","enum":["regular_annual"]},"profile":{"type":"object","properties":{"business_form":{"type":["string","null"],"enum":["sp","doo","dno","club",null],"description":"Canonical Slovenian legal form for the entity.","example":"sp"},"income_tax_regime":{"type":["string","null"],"enum":["normirani","dejanski",null],"description":"Income tax regime used by the Slovenian entity.","example":"normirani"},"vat_profile":{"type":["string","null"],"enum":["standard","special_vat_identified","non_vat_subject",null],"description":"Slovenia-specific VAT subject subtype.","example":"standard"},"tax_residency":{"type":["string","null"],"enum":["resident","non_resident",null],"description":"Tax residency status for Slovenian yearly reporting.","example":"resident"},"yearly_reporting":{"type":"object","properties":{"activity_codes":{"type":"array","items":{"type":"string","pattern":"^\\d{2}\\.\\d{3}$","description":"Slovenian SKD activity code used for yearly reporting.","example":"62.010"},"description":"Ordered SKD activity codes.","example":["62.010","47.910"]},"registration_number":{"type":["string","null"],"description":"Optional registration number used in the filing.","example":"1234567"},"accounting_type":{"type":["string","null"],"enum":["records","single_entry","double_entry",null],"description":"Accounting / records mode used in the filing.","example":"records"},"normiranec_insurance_basis":{"type":["string","null"],"enum":["full_time_self_employed","other",null],"description":"Insurance basis used by normirani rules.","example":"full_time_self_employed"},"default_withholding_tax_amount":{"type":["number","null"],"minimum":0,"description":"Persisted default withholding tax amount for yearly reviews.","example":0},"default_foreign_tax_credit_amount":{"type":["number","null"],"minimum":0,"description":"Persisted default foreign tax credit amount for yearly reviews.","example":0}},"required":["activity_codes","registration_number","accounting_type","normiranec_insurance_basis","default_withholding_tax_amount","default_foreign_tax_credit_amount"]},"accounting_exports":{"type":"object","properties":{"preferred_format":{"type":["string","null"],"enum":["vod_xml","vasco_xml","minimax_xml",null],"description":"Preferred Slovenian accounting export format.","example":"vod_xml"},"konto_mappings":{"allOf":[{"$ref":"#/components/schemas/SloveniaAccountingKontoMappings"},{"description":"Normalized semantic konto mappings shared by Slovenian accounting exports."}]}},"required":["preferred_format","konto_mappings"]},"business_form_source":{"type":"string","enum":["stored","registry","unknown"]},"inferred_business_form":{"type":["string","null"],"enum":["sp","doo","dno","club",null],"description":"Canonical Slovenian legal form for the entity.","example":"sp"},"supported_exports":{"type":"object","properties":{"yearly_normirani":{"type":"boolean"},"vod_xml":{"type":"boolean"},"vasco_xml":{"type":"boolean"},"minimax_xml":{"type":"boolean"}},"required":["yearly_normirani","vod_xml","vasco_xml","minimax_xml"]},"unsupported_reason":{"type":["string","null"]}},"required":["business_form","income_tax_regime","vat_profile","tax_residency","yearly_reporting","accounting_exports","business_form_source","inferred_business_form","supported_exports","unsupported_reason"]},"auto_values":{"type":"object","properties":{"total_invoice_revenue":{"type":"number"},"total_credit_note_reduction":{"type":"number"},"computed_revenue":{"type":"number"},"adjusted_revenue":{"type":"number"},"normative_expense_rate":{"type":"number"},"normative_expenses":{"type":"number"},"tax_base":{"type":"number"},"income_tax_rate":{"type":"number"},"income_tax_amount":{"type":"number"},"advance_tax_amount":{"type":"number"},"monthly_installment_amount":{"type":"number"},"quarterly_installment_amount":{"type":"number"}},"required":["total_invoice_revenue","total_credit_note_reduction","computed_revenue","adjusted_revenue","normative_expense_rate","normative_expenses","tax_base","income_tax_rate","income_tax_amount","advance_tax_amount","monthly_installment_amount","quarterly_installment_amount"]},"manual_values":{"type":"object","properties":{"withholding_tax_amount":{"type":"number","minimum":0,"description":"Monetary amount in EUR.","example":0},"foreign_tax_credit_amount":{"type":"number","minimum":0,"description":"Monetary amount in EUR.","example":0},"prior_advance_income_tax_amount":{"type":"number","minimum":0,"description":"Monetary amount in EUR.","example":0},"revenue_adjustment_decrease":{"type":"number","minimum":0,"description":"Monetary amount in EUR.","example":0},"revenue_adjustment_increase":{"type":"number","minimum":0,"description":"Monetary amount in EUR.","example":0}},"required":["withholding_tax_amount","foreign_tax_credit_amount","prior_advance_income_tax_amount","revenue_adjustment_decrease","revenue_adjustment_increase"]},"derived_flags":{"type":"object","properties":{"has_foreign_customers":{"type":"boolean"},"has_foreign_tax_numbers":{"type":"boolean"},"has_non_eur_documents":{"type":"boolean"}},"required":["has_foreign_customers","has_foreign_tax_numbers","has_non_eur_documents"]},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"severity":{"type":"string","enum":["info","warning"]}},"required":["code","message","severity"]}},"issue_details":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"explanation":{"type":"string"},"action":{"type":["string","null"]},"severity":{"type":"string","enum":["info","warning"]},"official_sources":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string","format":"uri"},"issuer":{"type":"string","enum":["FURS","PISRS"]}},"required":["label","url","issuer"]}},"affected_documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["invoice","credit_note"]},"number":{"type":"string"},"date":{"type":"string"},"customer_name":{"type":["string","null"]},"customer_country_code":{"type":["string","null"]},"customer_tax_number":{"type":["string","null"]},"currency_code":{"type":"string"},"total":{"type":"number"},"total_converted":{"type":["number","null"]},"reason":{"type":"string"},"document_path":{"type":"string"}},"required":["id","type","number","date","customer_name","customer_country_code","customer_tax_number","currency_code","total","total_converted","reason","document_path"]}}},"required":["code","title","summary","explanation","action","severity","official_sources","affected_documents"]}},"rule_summary":{"type":"object","properties":{"normative_expense_rule":{"type":"string"},"income_tax_rule":{"type":"string"},"advance_rule":{"type":"string"}},"required":["normative_expense_rule","income_tax_rule","advance_rule"]}},"required":["entity_id","year","filing_kind","profile","auto_values","manual_values","derived_flags","warnings","issue_details","rule_summary"]},"example":{"entity_id":"ent_sl_1","year":2025,"filing_kind":"regular_annual","profile":{"business_form":"sp","income_tax_regime":"normirani","vat_profile":"standard","tax_residency":"resident","yearly_reporting":{"activity_codes":["62.010","47.910"],"registration_number":"1234567","accounting_type":"records","normiranec_insurance_basis":"full_time_self_employed","default_withholding_tax_amount":0,"default_foreign_tax_credit_amount":0},"accounting_exports":{"preferred_format":"vod_xml","konto_mappings":{"receivables":"1200","payables":"2200","sales_vat_22":"26000","sales_vat_95":"26001","sales_vat_5":"26002","purchase_vat_recoverable_22":"16000","purchase_vat_recoverable_95":"16001","purchase_vat_recoverable_5":"16002","sales_revenue_22":"7600","sales_revenue_95":"7601","sales_revenue_5":"7602","sales_revenue_exempt":"7680","sales_revenue_eu_goods":"7600","sales_revenue_eu_services":"7601","sales_revenue_reverse_charge":"7600","sales_revenue_third_country_goods":"7600","sales_revenue_third_country_services":"7680","purchase_expense_22":"4000","purchase_expense_95":"4001","purchase_expense_5":"4002","purchase_expense_exempt":"4680","purchase_expense_eu_goods":"4000","purchase_expense_eu_services":"4680","purchase_expense_reverse_charge":"4000","purchase_expense_third_country_goods":"4000","purchase_expense_third_country_services":"4680"}},"business_form_source":"stored","inferred_business_form":"sp","supported_exports":{"yearly_normirani":true,"vod_xml":true,"vasco_xml":false,"minimax_xml":false},"unsupported_reason":null},"auto_values":{"total_invoice_revenue":20000,"total_credit_note_reduction":2000,"computed_revenue":18000,"adjusted_revenue":18000,"normative_expense_rate":80,"normative_expenses":14400,"tax_base":3600,"income_tax_rate":20,"income_tax_amount":720,"advance_tax_amount":720,"monthly_installment_amount":60,"quarterly_installment_amount":0},"manual_values":{"withholding_tax_amount":0,"foreign_tax_credit_amount":0,"prior_advance_income_tax_amount":0,"revenue_adjustment_decrease":0,"revenue_adjustment_increase":0},"derived_flags":{"has_foreign_customers":false,"has_foreign_tax_numbers":false,"has_non_eur_documents":false},"warnings":[],"issue_details":[],"rule_summary":{"normative_expense_rule":"legacy","income_tax_rule":"legacy","advance_rule":"monthly"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tax-reports/si/yearly/normirani/export":{"post":{"operationId":"exportSloveniaYearlyNormiraniReport","summary":"Export yearly Slovenia normirani XML","description":"Generate a DDD-DDD XML file for the supported resident normirani s.p. path after the yearly review values are confirmed.","security":[{"Bearer":[]}],"tags":["Tax Reports"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Yearly export request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","minimum":2025,"maximum":2100,"description":"Tax year for the yearly Slovenia eDavki filing.","example":2025},"manual_values":{"type":"object","properties":{"withholding_tax_amount":{"type":"number","minimum":0,"description":"Monetary amount in EUR.","example":0},"foreign_tax_credit_amount":{"type":"number","minimum":0,"description":"Monetary amount in EUR.","example":0},"prior_advance_income_tax_amount":{"type":"number","minimum":0,"description":"Monetary amount in EUR.","example":0},"revenue_adjustment_decrease":{"type":"number","minimum":0,"description":"Monetary amount in EUR.","example":0},"revenue_adjustment_increase":{"type":"number","minimum":0,"description":"Monetary amount in EUR.","example":0}},"required":["withholding_tax_amount","foreign_tax_credit_amount","prior_advance_income_tax_amount","revenue_adjustment_decrease","revenue_adjustment_increase"]}},"required":["year","manual_values"]},"examples":{"ConfirmComputedValues":{"value":{"year":2025,"manual_values":{"withholding_tax_amount":0,"foreign_tax_credit_amount":0,"prior_advance_income_tax_amount":0,"revenue_adjustment_decrease":0,"revenue_adjustment_increase":0}},"description":"Export XML after reviewing automatic values and confirming manual adjustments."},"WithManualAdjustments":{"value":{"year":2025,"manual_values":{"withholding_tax_amount":120,"foreign_tax_credit_amount":0,"prior_advance_income_tax_amount":360,"revenue_adjustment_decrease":0,"revenue_adjustment_increase":250}},"description":"Export XML with the small set of manual tax values the API cannot infer from invoices."}}}}},"responses":{"200":{"description":"DDD-DDD yearly XML export file","content":{"application/xml":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tax-reports/si/accounting/vod/export":{"post":{"operationId":"exportSloveniaVodXml","summary":"Export Slovenia VOD XML ZIP","description":"Generate a legacy-compatible Slovenian VOD ZIP export for issued documents. The first release contains only VOD_izdani.xml.","security":[{"Bearer":[]}],"tags":["Tax Reports"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Requested date range for the VOD export","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date_from":{"type":"string","format":"date","description":"Inclusive document date in YYYY-MM-DD format.","example":"2025-01-31"},"date_to":{"type":"string","format":"date","description":"Inclusive document date in YYYY-MM-DD format.","example":"2025-01-31"}},"required":["date_from","date_to"]},"examples":{"Monthly":{"value":{"date_from":"2025-01-01","date_to":"2025-01-31"},"description":"Generate a monthly Slovenian VOD ZIP for issued documents."},"Quarter":{"value":{"date_from":"2025-01-01","date_to":"2025-03-31"},"description":"Generate a quarter VOD ZIP when the accounting workflow batches exports quarterly."}}}}},"responses":{"200":{"description":"Legacy-compatible Slovenian VOD ZIP archive","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/white-labels/current":{"get":{"operationId":"getCurrentWhiteLabel","summary":"Get current white-label configuration","description":"Returns the white-label configuration for the current domain. Uses the Origin or Referer header to detect the domain. This is used by the web app to determine which features to enable/disable.","tags":["White Labels"],"responses":{"200":{"description":"Current white-label configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhiteLabelConfig"},"example":{"slug":"space-invoices","name":"Space Invoices","environment":"production","hidden_features":[],"billing_enabled":false,"account_users_full_ui_enabled":true,"hide_new_features_by_default":false,"reviewed_feature_catalog_ids":[],"theme":null,"analytics":{"posthog_key":null,"posthog_host":"https://eu.i.posthog.com","posthog_track_embeds":false},"hal_app_id":null,"support_email":null}}}}}}},"/white-labels/me":{"get":{"operationId":"getMyWhiteLabel","summary":"Get white-label configuration for the current authenticated account","description":"Returns the white-label configuration resolved from the authenticated user's effective account context. This is used by native/mobile clients that do not have browser origin headers.","security":[{"Bearer":[]}],"tags":["White Labels"],"responses":{"200":{"description":"White-label configuration for the authenticated account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhiteLabelConfig"},"example":{"slug":"space-invoices","name":"Space Invoices","environment":"production","hidden_features":[],"billing_enabled":false,"account_users_full_ui_enabled":true,"hide_new_features_by_default":false,"reviewed_feature_catalog_ids":[],"theme":null,"analytics":{"posthog_key":null,"posthog_host":"https://eu.i.posthog.com","posthog_track_embeds":false},"hal_app_id":null,"support_email":null}}}},"401":{"description":"Authentication required"}}}},"/white-label-subscriptions":{"get":{"operationId":"getCurrentWLSubscription","summary":"Get current subscription","description":"Returns the current entity subscription with plan details and usage stats. Requires entity context.","tags":["White-Label Subscriptions"],"responses":{"200":{"description":"Current subscription with usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentSubscription"},"example":{"plan":{"id":"plan_123abc","slug":"advanced","name":"Advanced","billing_interval":"monthly","base_price_cents":1299,"limits":{"invoices_per_month":500,"annual_price_cents":12900},"features":["invoices","estimates","customers","items","pdf_export","business_units","financial_categories"],"is_free":false,"display_order":1},"status":"active","billing_interval":"monthly","current_period_start":"2025-01-01T00:00:00.000Z","current_period_end":"2025-01-31T23:59:59.999Z","store_billing":null,"usage":{"documents_count":42,"documents_limit":100,"period_start":"2025-01-01T00:00:00.000Z","period_end":"2025-01-31T23:59:59.999Z"}}}}}}}},"/white-label-subscriptions/plans":{"get":{"operationId":"getWLSubscriptionPlans","summary":"Get available plans","description":"Returns available subscription plans for the current white-label.","tags":["White-Label Subscriptions"],"responses":{"200":{"description":"Available plans","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailablePlans"},"example":{"plans":[{"id":"plan_simple","slug":"simple","name":"Simple","billing_interval":"monthly","base_price_cents":499,"limits":{"invoices_per_month":15,"annual_price_cents":4900},"features":["invoices","estimates","delivery_notes","email_sending"],"is_free":false,"display_order":0}],"current_plan_slug":"simple"}}}}}}},"/white-label-subscriptions/check-feature/{feature}":{"get":{"operationId":"checkWLFeature","summary":"Check feature access","description":"Checks if a specific feature is available on the current subscription plan.","tags":["White-Label Subscriptions"],"parameters":[{"schema":{"type":"string","description":"Feature slug to check","example":"furs"},"required":true,"description":"Feature slug to check","name":"feature","in":"path"}],"responses":{"200":{"description":"Feature check result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureCheck"},"example":{"feature":"furs","allowed":true,"requires_upgrade":false,"upgrade_plan_slug":null}}}}}}},"/white-label-subscriptions/check-limit/{resource}":{"get":{"operationId":"checkWLLimit","summary":"Check resource limit","description":"Checks if the current usage allows creating more of a resource type.","tags":["White-Label Subscriptions"],"parameters":[{"schema":{"type":"string","description":"Resource type to check (e.g., 'documents')","example":"documents"},"required":true,"description":"Resource type to check (e.g., 'documents')","name":"resource","in":"path"}],"responses":{"200":{"description":"Limit check result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitCheck"},"example":{"resource":"documents","allowed":true,"usage":42,"limit":100,"percentage":42}}}}}}},"/white-label-subscriptions/billing-email":{"patch":{"operationId":"updateWLSubscriptionBillingEmail","summary":"Update billing email","description":"Updates the billing email used for white-label subscription notifications and invoices.","tags":["White-Label Subscriptions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WLUpdateBillingEmailRequest"},"examples":{"set":{"summary":"Set billing email","value":{"billing_email":"billing@example.com"}},"clear":{"summary":"Clear billing email","value":{"billing_email":null}}}}}},"responses":{"200":{"description":"Updated billing email","content":{"application/json":{"schema":{"type":"object","properties":{"billing_email":{"type":["string","null"]}},"required":["billing_email"]},"example":{"billing_email":"billing@example.com"}}}}}}},"/subscriptions":{"get":{"operationId":"getCurrentSubscription","tags":["Subscriptions"],"summary":"Get current subscription and usage","description":"Returns the current account subscription tier, usage statistics, and limits","responses":{"200":{"description":"Current subscription and usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentUsageResponse"},"example":{"subscription":{"id":"sub_123abc","account_id":"acc_456def","tier":"free","spending_limit_cents":5000,"is_internal":false,"created_at":"2025-01-01T00:00:00.000Z","updated_at":"2025-01-01T00:00:00.000Z"},"usage":{"documents_count":5,"entities_active":1,"period_start":"2025-01-01T00:00:00.000Z","period_end":"2025-01-31T23:59:59.999Z"},"limits":{"entities":1,"documents_per_month":10},"is_over_limit":false}}}}}}},"/subscriptions/spending-limit":{"patch":{"operationId":"updateSpendingLimit","tags":["Subscriptions"],"summary":"Update spending limit","description":"Update the spending limit for metered tier subscriptions. Only applicable for metered accounts.","requestBody":{"description":"Spending limit update request","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSpendingLimitRequest"},"example":{"spending_limit_cents":10000}}}},"responses":{"200":{"description":"Spending limit updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSpendingLimitResponse"},"example":{"spending_limit_cents":10000}}}}}}},"/subscriptions/check-entity-limit":{"get":{"operationId":"checkEntityLimit","tags":["Subscriptions"],"summary":"Check if account can create new entity","description":"Returns whether the account can create a new production entity based on subscription tier","responses":{"200":{"description":"Entity limit check result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityLimitCheck"},"example":{"can_create":true,"current_count":1,"limit":1}}}}}}},"/order-integrations/shopify/authorize":{"post":{"operationId":"authorizeShopify","summary":"Start Shopify OAuth flow","description":"Generate a Shopify OAuth authorization URL. Redirect the user to this URL to authorize the Shopify connection.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Order Integrations"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Shopify Authorization Request","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shop_domain":{"type":"string","minLength":1,"description":"Shopify shop domain, e.g. myshop.myshopify.com","example":"myshop.myshopify.com"},"name":{"type":"string","description":"Integration name","example":"My Shopify Store"},"auto_process":{"type":"boolean","description":"Auto-create invoices on order receipt"},"send_invoice_email":{"type":"boolean","description":"Auto-send invoice email"},"issue_invoice_for_bank":{"type":"boolean","description":"Issue invoice (vs estimate) for unpaid bank transfers"},"issue_invoice_on_complete":{"type":"boolean","description":"Delay document until order is fulfilled/complete"},"auto_process_delay_seconds":{"type":"integer","minimum":0,"description":"Seconds to wait before processing (0 = immediate)"},"business_unit_id":{"type":["string","null"],"maxLength":36,"description":"Business unit to use for auto-created documents."}},"required":["shop_domain"],"additionalProperties":false},"examples":{"Minimal":{"value":{"shop_domain":"myshop.myshopify.com"},"description":"Start Shopify OAuth flow"},"Complete":{"value":{"shop_domain":"myshop.myshopify.com","name":"Horizon Launch Shopify","auto_process":true,"send_invoice_email":true,"issue_invoice_on_complete":true,"auto_process_delay_seconds":300},"description":"Start Shopify OAuth flow with auto-processing and document delivery options enabled"}}}}},"responses":{"200":{"description":"Shopify OAuth redirect URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopifyAuthorizeResponse"},"examples":{"Success":{"value":{"redirect_url":"https://myshop.myshopify.com/admin/oauth/authorize?client_id=...&scope=read_orders&redirect_uri=...&state=..."},"description":"Redirect URL for Shopify OAuth"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/order-integrations/shopify/resume-install":{"post":{"operationId":"resumeShopifyInstall","summary":"Resume Shopify install after app launch","description":"Continue a pending Shopify custom-app install after Shopify redirects the merchant back to the app URL.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Order Integrations"],"requestBody":{"description":"Shopify Resume Install Request","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopifyResumeInstallRequest"},"examples":{"PendingInstall":{"value":{"shop":"myshop.myshopify.com"},"description":"Resume a pending Shopify custom-app install after app launch."}}}}},"responses":{"200":{"description":"Shopify OAuth redirect URL for a pending install","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopifyResumeInstallResponse"},"examples":{"Success":{"value":{"redirect_url":"https://myshop.myshopify.com/admin/oauth/authorize?client_id=...&scope=read_orders&redirect_uri=...&state=...","entity_id":"ent_6595a27b5d35015c3ef0c3fd","frontend_origin":"https://v2.getapollo.io"},"description":"Redirect URL and resolved entity for the resumed install."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/order-integrations/{id}/sync-shopify":{"post":{"operationId":"syncShopifyOrders","summary":"Sync Shopify orders","description":"Fetch Shopify orders updated in the selected time window and upsert them into local orders. Missing orders are imported, existing orders are refreshed, and processing is queued separately. Existing clients retain one-request completion; set resumable=true to opt into bounded chunks, then repeat completion_state=resumable responses with next_cursor. Disabled-period checkpoints are persisted so repeated safe requests durably converge. Shopify throttling is retried twice with each wait capped at five seconds; an exhausted throttle returns 429 with Retry-After. If Shopify expires a stored REST page cursor, the server safely clears that checkpoint and restarts the exact window; idempotent event IDs make the replay safe.","security":[{"Bearer":[]}],"tags":["Order Integrations"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Sync Shopify Orders Request","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"updated_since":{"type":"string","format":"date-time","description":"Inclusive Shopify update window start."},"updated_until":{"type":"string","format":"date-time","description":"Inclusive Shopify update window end."},"cursor":{"type":"string","minLength":1,"maxLength":2048,"description":"Opaque cursor returned by an incomplete prior sync to resume its exact window."},"resumable":{"type":"boolean","description":"Opt into bounded, resumable processing. Omit for legacy one-request completion; cursor requests are always bounded."},"limit":{"type":"integer","minimum":1,"maximum":250,"description":"Shopify page size. The server also enforces total-order and page-count caps."}},"additionalProperties":false},"examples":{"Minimal":{"value":{},"description":"Sync recently updated Shopify orders using the default lookback window."},"CustomWindow":{"value":{"updated_since":"2026-03-20T00:00:00.000Z","updated_until":"2026-03-21T00:00:00.000Z","limit":100},"description":"Sync a specific Shopify update window with a custom page size."},"SmallBackfillWindow":{"value":{"updated_since":"2026-03-20T12:00:00.000Z","updated_until":"2026-03-20T13:00:00.000Z","limit":25,"resumable":true},"description":"Backfill a narrow update window using bounded, resumable processing."},"Resume":{"value":{"cursor":"eyJsYXN0X2lkIjo...","limit":100},"description":"Resume the exact bounded window from an earlier resumable response."}}}}},"responses":{"200":{"description":"Shopify sync summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncShopifyOrdersResponse"},"examples":{"Success":{"value":{"imported":12,"updated":4,"queued_for_processing":6,"total_seen":16,"window_start":"2026-03-20T00:00:00.000Z","window_end":"2026-03-21T00:00:00.000Z","complete":true,"truncated":false,"pages_fetched":1,"completion_state":"complete"},"description":"Shopify sync finished successfully."},"Resumable":{"value":{"imported":742,"updated":258,"queued_for_processing":113,"total_seen":1000,"window_start":"2026-03-20T00:00:00.000Z","window_end":"2026-03-21T00:00:00.000Z","complete":false,"truncated":true,"pages_fetched":4,"completion_state":"resumable","next_cursor":"eyJsYXN0X2lkIjo..."},"description":"The safe request cap was reached; resume with next_cursor until completion_state is complete."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"429":{"description":"Shopify rate limit remained active after bounded retries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/order-integrations":{"post":{"operationId":"createOrderIntegration","summary":"Create a new order integration","description":"Create a new order integration for receiving orders from external platforms.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Order Integrations"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Create Order Integration Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"source":{"type":"string","enum":["shopify","woocommerce","manual"],"default":"manual"},"auto_process":{"type":"boolean"},"auto_reissue_on_update":{"type":"boolean"},"locale":{"type":["string","null"],"maxLength":10},"business_unit_id":{"type":["string","null"],"maxLength":36},"business_premise_id":{"type":["string","null"],"maxLength":36},"electronic_device_id":{"type":["string","null"],"maxLength":36},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"required":["name"],"additionalProperties":false},"examples":{"Minimal":{"value":{"name":"Horizon Launch Store"},"description":"Minimal manual integration with only required fields"},"Auto-process paid orders":{"value":{"name":"Horizon Launch paid orders","source":"shopify","auto_process":true},"description":"Enable automatic invoice creation using the integration's default processing trigger."},"Manual review integration":{"value":{"name":"Horizon Launch review queue","source":"shopify","auto_process":false,"auto_reissue_on_update":false},"description":"Import orders without automatic invoice creation so operators can review each order first."},"Complete":{"value":{"name":"Horizon Launch Shopify","source":"shopify","auto_process":true,"metadata":{"store_url":"https://horizon-launch.myshopify.com"}},"description":"Complete integration with all optional fields"}}}}},"responses":{"201":{"description":"Created Order Integration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderIntegration"},"examples":{"Minimal":{"value":{"id":"oint_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","name":"Horizon Launch Store","source":"manual","is_active":true,"shop_domain":null,"scopes":null,"auto_process":false,"auto_process_on":"paid","default_payment_type":null,"send_invoice_email":true,"send_estimate_email":true,"attach_pdf_to_email":false,"issue_invoice_for_bank":false,"issue_invoice_on_complete":false,"auto_process_delay_seconds":0,"auto_reissue_on_update":false,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Created manual integration"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getOrderIntegrations","summary":"List all order integrations","description":"Retrieve a paginated list of order integrations with optional filtering and sorting.","security":[{"Bearer":[]}],"tags":["Order Integrations"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","name","source","created_at","updated_at","-id","-name","-source","-created_at","-updated_at"]},{"type":"array","items":{"type":"string","enum":["id","name","source","created_at","updated_at","-id","-name","-source","-created_at","-updated_at"]}}],"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, name, source, is_active, created_at, updated_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, name, source, is_active, created_at, updated_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"type":"string","description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","example":"Acme Corporation"},"required":false,"description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","name":"search","in":"query"},{"schema":{"type":"boolean","description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items."},"required":false,"description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.","name":"deleted","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of Order Integrations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderIntegration"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"oint_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","name":"Horizon Launch Store","source":"manual","is_active":true,"shop_domain":null,"scopes":null,"auto_process":false,"auto_process_on":"paid","default_payment_type":null,"send_invoice_email":true,"send_estimate_email":true,"attach_pdf_to_email":false,"issue_invoice_for_bank":false,"issue_invoice_on_complete":false,"auto_process_delay_seconds":0,"auto_reissue_on_update":false,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of order integrations"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/order-integrations/{id}":{"get":{"operationId":"getOrderIntegrationById","summary":"Get order integration by ID","description":"Retrieve a single order integration by its unique identifier.","security":[{"Bearer":[]}],"tags":["Order Integrations"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Order Integration instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderIntegration"},"examples":{"200":{"value":{"id":"oint_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","name":"Horizon Launch Store","source":"manual","is_active":true,"shop_domain":null,"scopes":null,"auto_process":false,"auto_process_on":"paid","default_payment_type":null,"send_invoice_email":true,"send_estimate_email":true,"attach_pdf_to_email":false,"issue_invoice_for_bank":false,"issue_invoice_on_complete":false,"auto_process_delay_seconds":0,"auto_reissue_on_update":false,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Created manual integration"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateOrderIntegration","summary":"Update an order integration","description":"Update an existing order integration. Only the provided fields will be updated. Disabling Shopify persists the inactive state before remote webhook cleanup; a 502 means cleanup remains pending and the same disable request can be retried safely. Re-enabling restores webhooks before activation and records a crash-recoverable catch-up boundary after activation commits.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Order Integrations"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Order Integration Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"auto_process":{"type":"boolean"},"auto_reissue_on_update":{"type":"boolean"},"locale":{"type":["string","null"],"maxLength":10},"business_unit_id":{"type":["string","null"],"maxLength":36},"business_premise_id":{"type":["string","null"],"maxLength":36},"electronic_device_id":{"type":["string","null"],"maxLength":36},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}},"is_active":{"type":"boolean"},"auto_process_on":{"type":"string","enum":["created","paid","fulfilled"]},"default_payment_type":{"type":"string"},"send_invoice_email":{"type":"boolean"},"send_estimate_email":{"type":"boolean"},"attach_pdf_to_email":{"type":"boolean"},"issue_invoice_for_bank":{"type":"boolean"},"issue_invoice_on_complete":{"type":"boolean"},"auto_process_delay_seconds":{"type":"integer","minimum":0}},"additionalProperties":false},"examples":{"Update name":{"value":{"name":"Horizon Launch Store EU"},"description":"Update integration name"},"Enable auto-processing":{"value":{"auto_process":true,"auto_process_on":"paid"},"description":"Enable automatic invoice creation when orders are paid"},"Delay fulfillment processing":{"value":{"auto_process":true,"auto_process_on":"fulfilled","auto_process_delay_seconds":900},"description":"Wait until fulfillment and then delay processing to let upstream order updates settle."},"Disable auto reissue":{"value":{"auto_reissue_on_update":false},"description":"Keep already processed orders stable even if upstream order data later changes."},"Enable PDF email attachments":{"value":{"attach_pdf_to_email":true},"description":"Attach the generated document PDF to automated Shopify emails in addition to the document link."}}}}},"responses":{"200":{"description":"Updated Order Integration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderIntegration"},"examples":{"Updated":{"value":{"id":"oint_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","name":"Horizon Launch Store","source":"manual","is_active":true,"shop_domain":null,"scopes":null,"auto_process":false,"auto_process_on":"paid","default_payment_type":null,"send_invoice_email":true,"send_estimate_email":true,"attach_pdf_to_email":false,"issue_invoice_for_bank":false,"issue_invoice_on_complete":false,"auto_process_delay_seconds":0,"auto_reissue_on_update":false,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Created manual integration"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteOrderIntegration","summary":"Delete an order integration","description":"Soft delete an order integration. Shopify integrations are first made inactive, then their owned webhooks are removed. A 502 leaves the integration inactive with cleanup pending; repeat the delete request safely to retry cleanup.","security":[{"Bearer":[]}],"tags":["Order Integrations"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Order Integration deleted successfully"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders":{"post":{"operationId":"createOrder","summary":"Create a new order","description":"Create a new order manually or from an external source.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Orders"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Create Order Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_integration_id":{"type":"string","maxLength":36},"source":{"type":"string","enum":["shopify","woocommerce","manual"],"description":"Order source platform"},"source_id":{"type":"string","maxLength":255},"source_order_number":{"type":["string","null"],"maxLength":100},"customer_name":{"type":["string","null"],"maxLength":255},"customer_email":{"type":["string","null"],"maxLength":255},"customer":{"anyOf":[{"$ref":"#/components/schemas/OrderCustomer"},{"type":"null"}]},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/OrderAddress"},{"type":"null"}]},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/OrderAddress"},{"type":"null"}]},"currency_code":{"type":"string","maxLength":3},"total":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_with_tax":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_discount":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_shipping":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"},"minItems":1},"payment_status":{"type":"string","enum":["unpaid","paid","partially_paid","refunded"],"description":"Order payment status"},"payment_method":{"type":["string","null"],"maxLength":50},"payment_gateway":{"type":["string","null"],"maxLength":100},"ordered_at":{"type":["string","null"],"format":"date-time"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"required":["order_integration_id","source","source_id","currency_code","total","total_with_tax","items"],"additionalProperties":false},"examples":{"Minimal":{"value":{"order_integration_id":"oint_6595a27b5d35015c3ef0c3fd","source":"manual","source_id":"manual-001","currency_code":"EUR","total":100,"total_with_tax":122,"items":[{"name":"Payload Adapter Kit","quantity":2,"price":50,"gross_price":61,"total":100,"total_with_tax":122,"tax_rate":22}]},"description":"Minimal order with required fields"},"Paid Shopify order":{"value":{"order_integration_id":"oint_6595a27b5d35015c3ef0c3fd","source":"shopify","source_id":"5678901234","source_order_number":"#1234","currency_code":"EUR","total":100,"total_with_tax":122,"payment_status":"paid","payment_method":"card","payment_gateway":"shopify_payments","items":[{"name":"Payload Adapter Kit","quantity":1,"price":100,"gross_price":122,"total":100,"total_with_tax":122,"tax_rate":22,"sku":"PAK-001"}]},"description":"Order payload ready for paid-order automation."},"Refunded Shopify order":{"value":{"order_integration_id":"oint_6595a27b5d35015c3ef0c3fd","source":"shopify","source_id":"5678901235","source_order_number":"#1235","currency_code":"EUR","total":100,"total_with_tax":122,"payment_status":"refunded","items":[{"name":"Payload Adapter Kit","quantity":1,"price":100,"gross_price":122,"total":100,"total_with_tax":122,"tax_rate":22}],"metadata":{"shopify_financial_status":"refunded"}},"description":"Refunded orders are terminal for automation and should not create new documents."},"Complete":{"value":{"order_integration_id":"oint_6595a27b5d35015c3ef0c3fd","source":"shopify","source_id":"5678901234","source_order_number":"#1234","currency_code":"EUR","total":150,"total_with_tax":183,"total_discount":10,"total_shipping":5,"customer_name":"Horizon Launch Systems Inc.","customer_email":"orders@horizonlaunch.example","customer":{"phone":"+1-555-123-4567","company_name":"Horizon Launch Systems Inc.","tax_number":"74-1234567","is_business":true},"billing_address":{"address":"100 Rocket Row","city":"Houston","state":"TX","post_code":"77058","country":"US","country_code":"US"},"shipping_address":{"address":"200 Orbit Drive","city":"Cape Canaveral","state":"FL","post_code":"32920","country":"US","country_code":"US"},"items":[{"name":"Payload Adapter Kit","quantity":2,"price":50,"gross_price":61,"total":100,"total_with_tax":122,"tax_rate":22,"sku":"PAK-001"},{"name":"Telemetry Module","quantity":1,"price":50,"gross_price":61,"total":50,"total_with_tax":61,"tax_rate":22}],"payment_status":"paid","payment_method":"credit_card","payment_gateway":"stripe","ordered_at":"2024-01-15T10:30:00.000Z","metadata":{"shopify_order_id":"5678901234"}},"description":"Complete order with all fields"}}}}},"responses":{"201":{"description":"Created Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"examples":{"Minimal":{"value":{"id":"ord_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","order_integration_id":"oint_6595a27b5d35015c3ef0c3fd","source":"manual","source_id":"manual-001","source_order_number":null,"status":"pending","paid":false,"paid_at":null,"fulfilled":false,"fulfilled_at":null,"cancelled":false,"cancelled_at":null,"refunded":false,"refunded_at":null,"customer_name":null,"customer_email":null,"customer":null,"billing_address":null,"shipping_address":null,"customer_id":null,"currency_code":"EUR","total":100,"total_with_tax":122,"total_discount":0,"total_shipping":0,"items":[{"name":"Payload Adapter Kit","quantity":2,"price":50,"gross_price":61,"total":100,"total_with_tax":122,"tax_rate":22}],"payment_status":"unpaid","payment_method":null,"payment_gateway":null,"invoice_id":null,"estimate_id":null,"process_after":null,"transactions":[],"complete":false,"items_changed_after_processing":false,"raw_data":null,"source_event_id":null,"error":null,"ordered_at":null,"processed_at":null,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Created order"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getOrders","summary":"List all orders","description":"Retrieve a paginated list of orders with optional filtering and sorting.","security":[{"Bearer":[]}],"tags":["Orders"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Number of results per request."},"required":false,"description":"Number of results per request.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.","name":"prev_cursor","in":"query"},{"schema":{"type":"boolean","description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance."},"required":false,"description":"Whether to include the total count of items in `pagination.total`.\nDefault is `true`.\nWhen `false`, `pagination.total` returns -1 for better performance.","name":"include_total_count","in":"query"},{"schema":{"anyOf":[{"type":"string","enum":["id","status","source","customer_name","total","created_at","updated_at","-id","-status","-source","-customer_name","-total","-created_at","-updated_at"]},{"type":"array","items":{"type":"string","enum":["id","status","source","customer_name","total","created_at","updated_at","-id","-status","-source","-customer_name","-total","-created_at","-updated_at"]}}],"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering."},"required":false,"description":"Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with `-` for descending order. When paginating, reuse cursors only with the same effective ordering.","name":"order_by","in":"query"},{"schema":{"type":"string","format":"json","description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, status, source, source_id, customer_name, customer_email, payment_status, order_integration_id, ordered_at, created_at, updated_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","examples":["{\"total\": {\"gte\": 1000}}","{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}"]},"required":false,"description":"JSON query object for filtering results. Supports MongoDB-style operators.\n\n**Supported operators:**\n- `equals` or direct value - Exact match (default)\n- `gte` - Greater than or equal\n- `lte` - Less than or equal\n- `gt` - Greater than\n- `lt` - Less than\n- `in` - Value in array\n- `notIn` - Value not in array\n- `contains` - String contains (case-insensitive)\n- `startsWith` - String starts with\n- `endsWith` - String ends with\n- `between` - Value between two numbers/dates [min, max]\n\n**Allowed fields:** id, status, source, source_id, customer_name, customer_email, payment_status, order_integration_id, ordered_at, created_at, updated_at\n\n**Examples:**\n- `{\"total\": {\"gte\": 1000}}` - Invoices over 1000\n- `{\"customer.name\": {\"contains\": \"Acme\"}}` - Customer name contains \"Acme\"\n- `{\"date\": {\"between\": [\"2025-01-01\", \"2025-12-31\"]}}` - Date range","name":"query","in":"query"},{"schema":{"type":"string","description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","example":"Acme Corporation"},"required":false,"description":"Full-text search query to filter results across multiple fields.\nSearches are case-insensitive and match partial strings.\nSearches across all text fields including names, descriptions, addresses, and metadata values.","name":"search","in":"query"},{"schema":{"type":"boolean","description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items."},"required":false,"description":"When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.","name":"deleted","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"List of Orders","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"examples":{"200":{"value":{"data":[{"id":"ord_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","order_integration_id":"oint_6595a27b5d35015c3ef0c3fd","source":"manual","source_id":"manual-001","source_order_number":null,"status":"pending","paid":false,"paid_at":null,"fulfilled":false,"fulfilled_at":null,"cancelled":false,"cancelled_at":null,"refunded":false,"refunded_at":null,"customer_name":null,"customer_email":null,"customer":null,"billing_address":null,"shipping_address":null,"customer_id":null,"currency_code":"EUR","total":100,"total_with_tax":122,"total_discount":0,"total_shipping":0,"items":[{"name":"Payload Adapter Kit","quantity":2,"price":50,"gross_price":61,"total":100,"total_with_tax":122,"tax_rate":22}],"payment_status":"unpaid","payment_method":null,"payment_gateway":null,"invoice_id":null,"estimate_id":null,"process_after":null,"transactions":[],"complete":false,"items_changed_after_processing":false,"raw_data":null,"source_event_id":null,"error":null,"ordered_at":null,"processed_at":null,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null}],"pagination":{"total":1,"next_cursor":null,"prev_cursor":null,"has_more":false}},"description":"Paginated list of orders"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}":{"get":{"operationId":"getOrderById","summary":"Get order by ID","description":"Retrieve a single order by its unique identifier.","security":[{"Bearer":[]}],"tags":["Orders"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Order instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"examples":{"200":{"value":{"id":"ord_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","order_integration_id":"oint_6595a27b5d35015c3ef0c3fd","source":"manual","source_id":"manual-001","source_order_number":null,"status":"pending","paid":false,"paid_at":null,"fulfilled":false,"fulfilled_at":null,"cancelled":false,"cancelled_at":null,"refunded":false,"refunded_at":null,"customer_name":null,"customer_email":null,"customer":null,"billing_address":null,"shipping_address":null,"customer_id":null,"currency_code":"EUR","total":100,"total_with_tax":122,"total_discount":0,"total_shipping":0,"items":[{"name":"Payload Adapter Kit","quantity":2,"price":50,"gross_price":61,"total":100,"total_with_tax":122,"tax_rate":22}],"payment_status":"unpaid","payment_method":null,"payment_gateway":null,"invoice_id":null,"estimate_id":null,"process_after":null,"transactions":[],"complete":false,"items_changed_after_processing":false,"raw_data":null,"source_event_id":null,"error":null,"ordered_at":null,"processed_at":null,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Created order"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateOrder","summary":"Update an order","description":"Update an existing order. Only the provided fields will be updated.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["Orders"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"requestBody":{"description":"Update Order Request Body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source_order_number":{"type":["string","null"],"maxLength":100},"customer_name":{"type":["string","null"],"maxLength":255},"customer_email":{"type":["string","null"],"maxLength":255},"customer":{"anyOf":[{"$ref":"#/components/schemas/OrderCustomer"},{"type":"null"}]},"billing_address":{"anyOf":[{"$ref":"#/components/schemas/OrderAddress"},{"type":"null"}]},"shipping_address":{"anyOf":[{"$ref":"#/components/schemas/OrderAddress"},{"type":"null"}]},"currency_code":{"type":"string","maxLength":3},"total":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_with_tax":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_discount":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_shipping":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"},"minItems":1},"payment_status":{"type":"string","enum":["unpaid","paid","partially_paid","refunded"],"description":"Order payment status"},"payment_method":{"type":["string","null"],"maxLength":50},"payment_gateway":{"type":["string","null"],"maxLength":100},"ordered_at":{"type":["string","null"],"format":"date-time"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom key-value data for your own use. Store any JSON object up to 50 properties. Values must be strings up to 250 characters. Useful for storing external IDs, tags, or integration data.","example":{"external_id":"123","source":"shopify"}}},"additionalProperties":false},"examples":{"Update customer":{"value":{"customer_name":"Updated Customer Name","customer_email":"updated@example.com"},"description":"Update order customer info"},"Mark refunded":{"value":{"payment_status":"refunded","metadata":{"refund_reason":"Customer returned the full order"}},"description":"Record a full upstream refund so automation treats the order as terminal."}}}}},"responses":{"200":{"description":"Updated Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"examples":{"Updated":{"value":{"id":"ord_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","order_integration_id":"oint_6595a27b5d35015c3ef0c3fd","source":"manual","source_id":"manual-001","source_order_number":null,"status":"pending","paid":false,"paid_at":null,"fulfilled":false,"fulfilled_at":null,"cancelled":false,"cancelled_at":null,"refunded":false,"refunded_at":null,"customer_name":null,"customer_email":null,"customer":null,"billing_address":null,"shipping_address":null,"customer_id":null,"currency_code":"EUR","total":100,"total_with_tax":122,"total_discount":0,"total_shipping":0,"items":[{"name":"Payload Adapter Kit","quantity":2,"price":50,"gross_price":61,"total":100,"total_with_tax":122,"tax_rate":22}],"payment_status":"unpaid","payment_method":null,"payment_gateway":null,"invoice_id":null,"estimate_id":null,"process_after":null,"transactions":[],"complete":false,"items_changed_after_processing":false,"raw_data":null,"source_event_id":null,"error":null,"ordered_at":null,"processed_at":null,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Created order"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteOrder","summary":"Delete an order","description":"Soft delete an order by its unique identifier.","security":[{"Bearer":[]}],"tags":["Orders"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"204":{"description":"Order deleted successfully"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/process":{"post":{"operationId":"processOrder","summary":"Process an order into an invoice","description":"Process a pending order: resolve or create customer, generate invoice, and optionally record payment.","security":[{"Bearer":[]}],"tags":["Orders"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Processed Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"examples":{"Success":{"value":{"id":"ord_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","order_integration_id":"oint_6595a27b5d35015c3ef0c3fd","source":"manual","source_id":"manual-001","source_order_number":null,"status":"invoiced","paid":false,"paid_at":null,"fulfilled":false,"fulfilled_at":null,"cancelled":false,"cancelled_at":null,"refunded":false,"refunded_at":null,"customer_name":null,"customer_email":null,"customer":null,"billing_address":null,"shipping_address":null,"customer_id":null,"currency_code":"EUR","total":100,"total_with_tax":122,"total_discount":0,"total_shipping":0,"items":[{"name":"Payload Adapter Kit","quantity":2,"price":50,"gross_price":61,"total":100,"total_with_tax":122,"tax_rate":22}],"payment_status":"unpaid","payment_method":null,"payment_gateway":null,"invoice_id":"inv_7595a27b5d35015c3ef0c3fe","estimate_id":null,"process_after":null,"transactions":[],"complete":false,"items_changed_after_processing":false,"raw_data":null,"source_event_id":null,"error":null,"ordered_at":null,"processed_at":"2024-01-15T12:00:00.000Z","metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Processed order with linked invoice"},"SkippedTerminalOrder":{"value":{"id":"ord_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","order_integration_id":"oint_6595a27b5d35015c3ef0c3fd","source":"manual","source_id":"manual-001","source_order_number":null,"status":"cancelled","paid":false,"paid_at":null,"fulfilled":false,"fulfilled_at":null,"cancelled":true,"cancelled_at":null,"refunded":false,"refunded_at":null,"customer_name":null,"customer_email":null,"customer":null,"billing_address":null,"shipping_address":null,"customer_id":null,"currency_code":"EUR","total":100,"total_with_tax":122,"total_discount":0,"total_shipping":0,"items":[{"name":"Payload Adapter Kit","quantity":2,"price":50,"gross_price":61,"total":100,"total_with_tax":122,"tax_rate":22}],"payment_status":"refunded","payment_method":null,"payment_gateway":null,"invoice_id":null,"estimate_id":null,"process_after":null,"transactions":[],"complete":false,"items_changed_after_processing":false,"raw_data":null,"source_event_id":null,"error":null,"ordered_at":null,"processed_at":null,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Refunded or cancelled orders are terminal and are not auto-processed into documents."}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/cancel":{"post":{"operationId":"cancelOrder","summary":"Cancel an order","description":"Cancel a pending order. Already invoiced orders cannot be cancelled.","security":[{"Bearer":[]}],"tags":["Orders"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Cancelled Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"examples":{"Success":{"value":{"id":"ord_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","order_integration_id":"oint_6595a27b5d35015c3ef0c3fd","source":"manual","source_id":"manual-001","source_order_number":null,"status":"cancelled","paid":false,"paid_at":null,"fulfilled":false,"fulfilled_at":null,"cancelled":true,"cancelled_at":"2024-01-15T12:00:00.000Z","refunded":false,"refunded_at":null,"customer_name":null,"customer_email":null,"customer":null,"billing_address":null,"shipping_address":null,"customer_id":null,"currency_code":"EUR","total":100,"total_with_tax":122,"total_discount":0,"total_shipping":0,"items":[{"name":"Payload Adapter Kit","quantity":2,"price":50,"gross_price":61,"total":100,"total_with_tax":122,"tax_rate":22}],"payment_status":"unpaid","payment_method":null,"payment_gateway":null,"invoice_id":null,"estimate_id":null,"process_after":null,"transactions":[],"complete":false,"items_changed_after_processing":false,"raw_data":null,"source_event_id":null,"error":null,"ordered_at":null,"processed_at":null,"metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Cancelled order"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/reissue":{"post":{"operationId":"reissueOrder","summary":"Reissue an order invoice","description":"Credit the existing invoice and create a new one with current order items. Only available when order items have changed after initial processing.","security":[{"Bearer":[]}],"tags":["Orders"],"parameters":[{"schema":{"type":"string","format":"resource-id","pattern":"^[a-z]{3,4}_[0-9a-f]{24}$","description":"Unique resource identifier","example":"inv_6595a27b5d35015c3ef0c3fd"},"required":true,"description":"Unique resource identifier","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","example":"ent_507f1f77bcf86cd799439011"},"required":false,"description":"Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.","name":"x-entity-id","in":"header"}],"responses":{"200":{"description":"Reissued Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"examples":{"Success":{"value":{"id":"ord_6595a27b5d35015c3ef0c3fd","entity_id":"ent_6595a27b5d35015c3ef0c3fd","order_integration_id":"oint_6595a27b5d35015c3ef0c3fd","source":"manual","source_id":"manual-001","source_order_number":null,"status":"invoiced","paid":false,"paid_at":null,"fulfilled":false,"fulfilled_at":null,"cancelled":false,"cancelled_at":null,"refunded":false,"refunded_at":null,"customer_name":null,"customer_email":null,"customer":null,"billing_address":null,"shipping_address":null,"customer_id":null,"currency_code":"EUR","total":100,"total_with_tax":122,"total_discount":0,"total_shipping":0,"items":[{"name":"Payload Adapter Kit","quantity":2,"price":50,"gross_price":61,"total":100,"total_with_tax":122,"tax_rate":22}],"payment_status":"unpaid","payment_method":null,"payment_gateway":null,"invoice_id":"inv_8595a27b5d35015c3ef0c3ff","estimate_id":null,"process_after":null,"transactions":[],"complete":false,"items_changed_after_processing":false,"raw_data":null,"source_event_id":null,"error":null,"ordered_at":null,"processed_at":"2024-01-16T12:00:00.000Z","metadata":{},"created_at":"2024-01-01T00:00:00.000Z","updated_at":"2024-09-01T00:00:00.000Z","deleted_at":null},"description":"Reissued order with new invoice"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stripe-app/authorize":{"get":{"operationId":"stripeAppAuthorize","summary":"Start Stripe App connection","description":"Generate a state token and redirect URL for the Apollo onboarding flow.","tags":["Stripe App"],"parameters":[{"schema":{"type":"string","description":"Stripe account ID from the Stripe App context","example":"acct_1234567890"},"required":true,"description":"Stripe account ID from the Stripe App context","name":"stripe-user-account-id","in":"header"}],"responses":{"200":{"description":"Redirect URL for Apollo authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAppAuthorizeResponse"},"examples":{"200":{"value":{"redirect_url":"https://v2.getapollo.io/stripe-app-link?state=sa_state_abc123def456789012345678abcd1234"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stripe-app/oauth/callback":{"get":{"operationId":"stripeAppOAuthCallback","summary":"OAuth callback from Stripe","description":"Handles the OAuth callback from Stripe. Exchanges the authorization code for tokens and redirects to Apollo frontend.","tags":["Stripe App"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"OAuth authorization code from Stripe"},"required":true,"description":"OAuth authorization code from Stripe","name":"code","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Encrypted state token from the authorize step"},"required":true,"description":"Encrypted state token from the authorize step","name":"state","in":"query"}],"responses":{"302":{"description":"Redirect to Apollo frontend with connect state"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stripe-app/webhooks":{"post":{"operationId":"stripeAppWebhook","summary":"Handle Stripe App webhook","description":"Receive and process Stripe webhook events for auto-invoice creation.","tags":["Stripe App"],"responses":{"200":{"description":"Webhook received","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAppWebhookResponse"},"examples":{"200":{"value":{"received":true}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stripe-app/marketplace-authorize":{"post":{"operationId":"stripeAppMarketplaceAuthorize","summary":"Start marketplace OAuth flow","description":"Initiate the Stripe OAuth flow from the Apollo web app. Returns a Stripe OAuth URL that the frontend should redirect the user to.","security":[{"Bearer":[]}],"tags":["Stripe App"],"requestBody":{"description":"Entity to connect","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entity_id":{"type":"string","minLength":1,"description":"Entity ID to connect to the Stripe account","example":"ent_507f1f77bcf86cd799439011"}},"required":["entity_id"],"additionalProperties":false},"examples":{"Connect entity via marketplace":{"description":"Initiate Stripe OAuth from the Apollo web app for marketplace install flow","value":{"entity_id":"ent_507f1f77bcf86cd799439011"}}}}}},"responses":{"200":{"description":"Stripe OAuth redirect URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAppAuthorizeResponse"},"examples":{"200":{"value":{"redirect_url":"https://marketplace.stripe.com/oauth/v2/authorize?client_id=ca_xxx&redirect_uri=https%3A%2F%2Feu.spaceinvoices.com%2Fstripe-app%2Foauth%2Fcallback&state=sa_mkt_abc123"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stripe-app/connect":{"post":{"operationId":"stripeAppConnect","summary":"Complete Stripe App connection","description":"Complete the connection between a Stripe account and a Space Invoices entity. Requires bearer authentication (user must be signed in to Apollo).","security":[{"Bearer":[]}],"tags":["Stripe App"],"requestBody":{"description":"Connection parameters","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","minLength":1,"description":"State token from the authorize step","example":"sa_state_abc123def456789012345678abcd1234"},"entity_id":{"type":"string","minLength":1,"description":"Entity ID to connect to the Stripe account","example":"ent_507f1f77bcf86cd799439011"},"force":{"type":"boolean","description":"If true, disconnects any existing connection for this Stripe account before connecting"}},"required":["state","entity_id"],"additionalProperties":false},"examples":{"Connect entity":{"description":"Complete the Stripe App connection by linking an entity","value":{"state":"sa_state_abc123def456789012345678abcd1234","entity_id":"ent_507f1f77bcf86cd799439011"}}}}}},"responses":{"201":{"description":"Connection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAppConnection"},"examples":{"201":{"value":{"id":"sac_507f1f77bcf86cd799439011","stripe_account_id":"acct_1234567890","entity_id":"ent_507f1f77bcf86cd799439011","white_label_id":"wl_apollo","auto_invoice_config":{"enabled":false,"events":[]},"created_at":"2024-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stripe-app/connection":{"get":{"operationId":"stripeAppGetConnection","summary":"Get connection status","description":"Get the current Stripe App connection status and configuration.","tags":["Stripe App"],"parameters":[{"schema":{"type":"string","description":"Stripe account ID"},"required":true,"description":"Stripe account ID","name":"stripe-user-account-id","in":"header"}],"responses":{"200":{"description":"Connection details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAppConnection"},"examples":{"200":{"value":{"id":"sac_507f1f77bcf86cd799439011","stripe_account_id":"acct_1234567890","entity_id":"ent_507f1f77bcf86cd799439011","white_label_id":"wl_apollo","auto_invoice_config":{"enabled":true,"events":["payment_intent.succeeded"]},"created_at":"2024-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"stripeAppDisconnect","summary":"Disconnect Stripe App","description":"Remove the connection between Stripe and Space Invoices. Deletes the stored API key.","tags":["Stripe App"],"parameters":[{"schema":{"type":"string","description":"Stripe account ID"},"required":true,"description":"Stripe account ID","name":"stripe-user-account-id","in":"header"}],"responses":{"200":{"description":"Disconnected","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"examples":{"200":{"value":{"message":"Stripe App disconnected"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stripe-app/settings":{"get":{"operationId":"stripeAppGetSettings","summary":"Get auto-invoice settings","description":"Get the auto-invoice configuration for this connection.","tags":["Stripe App"],"parameters":[{"schema":{"type":"string","description":"Stripe account ID"},"required":true,"description":"Stripe account ID","name":"stripe-user-account-id","in":"header"}],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAppSettings"},"examples":{"200":{"value":{"auto_invoice_enabled":true,"auto_invoice_events":["payment_intent.succeeded"],"default_note":"Thank you for your order from Horizon Launch Systems.","default_tax_rate":null}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"stripeAppUpdateSettings","summary":"Update auto-invoice settings","description":"Update the auto-invoice configuration for this connection.","tags":["Stripe App"],"parameters":[{"schema":{"type":"string","description":"Stripe account ID"},"required":true,"description":"Stripe account ID","name":"stripe-user-account-id","in":"header"}],"requestBody":{"description":"Settings update","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"auto_invoice_enabled":{"type":"boolean","description":"Enable or disable auto-invoicing"},"auto_invoice_events":{"type":"array","items":{"type":"string","enum":["payment_intent.succeeded","invoice.paid"]},"description":"Stripe event types that trigger auto-invoice creation"},"default_note":{"type":"string","maxLength":500,"description":"Default note to include on auto-created invoices"},"default_tax_rate":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Default tax rate (%) to apply to auto-created invoices when Stripe data has no tax info. Set to null to disable.","example":22}},"additionalProperties":false},"examples":{"Enable auto-invoicing":{"description":"Enable auto-invoice creation for payment events","value":{"auto_invoice_enabled":true,"auto_invoice_events":["payment_intent.succeeded"],"default_note":"Thank you for your order from Horizon Launch Systems."}},"Invoice Stripe subscriptions":{"description":"Enable invoice creation from paid Stripe invoices as well as one-off payment intents","value":{"auto_invoice_enabled":true,"auto_invoice_events":["payment_intent.succeeded","invoice.paid"],"default_note":"Invoice generated from Stripe payment."}},"Apply fallback tax rate":{"description":"Use a default tax rate when Stripe payment or invoice line items do not include tax details","value":{"default_tax_rate":22}},"Clear fallback tax rate":{"description":"Remove the fallback tax rate and only use tax data provided by Stripe","value":{"default_tax_rate":null}},"Disable auto-invoicing":{"description":"Keep the connection active but stop creating invoices automatically","value":{"auto_invoice_enabled":false,"auto_invoice_events":[]}}}}}},"responses":{"200":{"description":"Updated settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAppSettings"},"examples":{"200":{"value":{"auto_invoice_enabled":true,"auto_invoice_events":["payment_intent.succeeded"],"default_note":"Thank you for your order from Horizon Launch Systems.","default_tax_rate":null}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stripe-app/invoices":{"post":{"operationId":"stripeAppCreateInvoice","summary":"Create invoice from Stripe object","description":"Create a Space Invoices invoice from a Stripe object ID. The backend fetches the full object from Stripe API and extracts customer, line items, and tax data.","tags":["Stripe App"],"parameters":[{"schema":{"type":"string","description":"Stripe account ID"},"required":true,"description":"Stripe account ID","name":"stripe-user-account-id","in":"header"}],"requestBody":{"description":"Stripe object reference","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stripe_object_id":{"type":"string","minLength":1,"description":"Stripe object ID (pi_xxx for payment intents, in_xxx for invoices). Type is auto-detected from prefix.","example":"pi_3abc123def456"},"note":{"type":"string","maxLength":2000,"description":"Optional note to include on the invoice"}},"required":["stripe_object_id"],"additionalProperties":false},"examples":{"From payment intent":{"description":"Create an invoice from a Stripe payment intent. Backend fetches all data from Stripe API.","value":{"stripe_object_id":"pi_3abc123def456","note":"Payment received via Stripe"}},"From Stripe invoice":{"description":"Create an invoice from a Stripe invoice. Backend fetches line items, tax rates, and customer data.","value":{"stripe_object_id":"in_1abc123def456"}},"From subscription invoice with note":{"description":"Create an invoice from a paid Stripe subscription invoice and add a custom note.","value":{"stripe_object_id":"in_1subscription123","note":"Subscription period: 2024-01-01 to 2024-01-31"}}}}}},"responses":{"201":{"description":"Invoice created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAppInvoice"},"examples":{"201":{"value":{"id":"inv_507f1f77bcf86cd799439011","number":"INV-2024-001","status":"draft","total":183,"currency":"EUR","public_url":"https://v2.getapollo.io/embed/documents/view/abc123","fiscalization_status":null,"created_at":"2024-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"stripeAppListInvoices","summary":"List invoices","description":"List recent invoices for the connected entity.","tags":["Stripe App"],"parameters":[{"schema":{"type":"number","minimum":1,"maximum":50,"default":10,"description":"Number of invoices to return"},"required":false,"description":"Number of invoices to return","name":"limit","in":"query"},{"schema":{"type":"string","description":"Stripe account ID"},"required":true,"description":"Stripe account ID","name":"stripe-user-account-id","in":"header"}],"responses":{"200":{"description":"List of invoices","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAppInvoiceList"},"examples":{"200":{"value":{"data":[{"id":"inv_507f1f77bcf86cd799439011","number":"INV-2024-001","status":"draft","total":183,"currency":"EUR","public_url":"https://v2.getapollo.io/embed/documents/view/abc123","fiscalization_status":null,"created_at":"2024-01-01T00:00:00.000Z"}]}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stripe-app/invoices/lookup":{"get":{"operationId":"stripeAppLookupInvoice","summary":"Look up invoice by Stripe object ID","description":"Find an Apollo invoice linked to a Stripe object (invoice or payment intent) via auto-invoicing events.","tags":["Stripe App"],"parameters":[{"schema":{"type":"string","minLength":1,"description":"Stripe object ID (e.g. in_xxx for invoices, pi_xxx for payment intents)","example":"in_1234567890"},"required":true,"description":"Stripe object ID (e.g. in_xxx for invoices, pi_xxx for payment intents)","name":"stripe_object_id","in":"query"},{"schema":{"type":"string","description":"Stripe account ID"},"required":true,"description":"Stripe account ID","name":"stripe-user-account-id","in":"header"}],"responses":{"200":{"description":"Invoice found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAppInvoice"},"examples":{"200":{"value":{"id":"inv_507f1f77bcf86cd799439011","number":"INV-2024-001","status":"draft","total":183,"currency":"EUR","public_url":"https://v2.getapollo.io/embed/documents/view/abc123","fiscalization_status":"fiscalized","created_at":"2024-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stripe-app/invoices/{id}":{"get":{"operationId":"stripeAppGetInvoice","summary":"Get invoice detail","description":"Get a specific invoice with public link and compliance/fiscalization status.","tags":["Stripe App"],"parameters":[{"schema":{"type":"string","description":"Invoice ID","example":"inv_507f1f77bcf86cd799439011"},"required":true,"description":"Invoice ID","name":"id","in":"path"},{"schema":{"type":"string","description":"Stripe account ID"},"required":true,"description":"Stripe account ID","name":"stripe-user-account-id","in":"header"}],"responses":{"200":{"description":"Invoice detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAppInvoice"},"examples":{"200":{"value":{"id":"inv_507f1f77bcf86cd799439011","number":"INV-2024-001","status":"draft","total":183,"currency":"EUR","public_url":"https://v2.getapollo.io/embed/documents/view/abc123","fiscalization_status":"fiscalized","created_at":"2024-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stripe-app/entity-connection":{"get":{"operationId":"stripeAppEntityGetConnection","summary":"Get entity Stripe connection","description":"Get the Stripe App connection status for the current entity. Returns 404 when not connected.","security":[{"Bearer":[]}],"tags":["Stripe App"],"responses":{"200":{"description":"Connection details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAppConnection"},"examples":{"200":{"value":{"id":"sac_507f1f77bcf86cd799439011","stripe_account_id":"acct_1234567890","entity_id":"ent_507f1f77bcf86cd799439011","white_label_id":"wl_apollo","auto_invoice_config":{"enabled":true,"events":["payment_intent.succeeded"]},"created_at":"2024-01-01T00:00:00.000Z"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"stripeAppEntityDisconnect","summary":"Disconnect entity Stripe connection","description":"Remove the Stripe App connection for the current entity.","security":[{"Bearer":[]}],"tags":["Stripe App"],"responses":{"200":{"description":"Disconnected","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"examples":{"200":{"value":{"message":"Stripe App disconnected"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stripe-app/entity-settings":{"get":{"operationId":"stripeAppEntityGetSettings","summary":"Get entity Stripe settings","description":"Get auto-invoice settings for the current entity's Stripe App connection.","security":[{"Bearer":[]}],"tags":["Stripe App"],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAppSettings"},"examples":{"200":{"value":{"auto_invoice_enabled":true,"auto_invoice_events":["payment_intent.succeeded"],"default_note":"Thank you for your order from Horizon Launch Systems.","default_tax_rate":null}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"stripeAppEntityUpdateSettings","summary":"Update entity Stripe settings","description":"Update auto-invoice settings for the current entity's Stripe App connection.","security":[{"Bearer":[]}],"tags":["Stripe App"],"requestBody":{"description":"Settings update","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"auto_invoice_enabled":{"type":"boolean","description":"Enable or disable auto-invoicing"},"auto_invoice_events":{"type":"array","items":{"type":"string","enum":["payment_intent.succeeded","invoice.paid"]},"description":"Stripe event types that trigger auto-invoice creation"},"default_note":{"type":"string","maxLength":500,"description":"Default note to include on auto-created invoices"},"default_tax_rate":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Default tax rate (%) to apply to auto-created invoices when Stripe data has no tax info. Set to null to disable.","example":22}},"additionalProperties":false},"examples":{"Enable auto-invoicing":{"description":"Enable auto-invoice creation for payment events","value":{"auto_invoice_enabled":true,"auto_invoice_events":["payment_intent.succeeded"],"default_note":"Thank you for your order from Horizon Launch Systems."}},"Invoice Stripe subscriptions":{"description":"Enable invoice creation from paid Stripe invoices as well as one-off payment intents","value":{"auto_invoice_enabled":true,"auto_invoice_events":["payment_intent.succeeded","invoice.paid"],"default_note":"Invoice generated from Stripe payment."}},"Apply fallback tax rate":{"description":"Use a default tax rate when Stripe payment or invoice line items do not include tax details","value":{"default_tax_rate":22}},"Clear fallback tax rate":{"description":"Remove the fallback tax rate and only use tax data provided by Stripe","value":{"default_tax_rate":null}},"Disable auto-invoicing":{"description":"Keep the connection active but stop creating invoices automatically","value":{"auto_invoice_enabled":false,"auto_invoice_events":[]}}}}}},"responses":{"200":{"description":"Updated settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeAppSettings"},"examples":{"200":{"value":{"auto_invoice_enabled":true,"auto_invoice_events":["payment_intent.succeeded"],"default_note":"Thank you for your order from Horizon Launch Systems.","default_tax_rate":null}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"Missing Required Field":{"summary":"Missing required field","description":"When a required field is missing from the request","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Required"]}}}},"Invalid Field Type":{"summary":"Invalid field type","description":"When a field has the wrong data type","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"date":{"_errors":["Expected string, received number"]}}}},"Array Validation":{"summary":"Array validation error","description":"When an array doesn't meet validation constraints","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Multiple Errors":{"summary":"Multiple validation errors","description":"When multiple fields have validation errors","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"name":{"_errors":["Required"]},"email":{"_errors":["Invalid email"]},"items":{"_errors":["Array must contain at least 1 element(s)"]}}}},"Nested Field Error":{"summary":"Nested field validation error","description":"When a nested field has a validation error","value":{"code":"validation_error","message":"Validation error","cause":{"_errors":[],"customer":{"name":{"_errors":["String must contain at least 1 character(s)"]},"address":{"postal_code":{"_errors":["String must contain at least 3 character(s)"]}}}}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/legacy-migration/auth":{"post":{"operationId":"legacyMigrationAuth","summary":"Authenticate with legacy API","description":"Authenticate with legacy Space Invoices credentials and get a list of owned organizations.","security":[{"Bearer":[]}],"tags":["Legacy Migration"],"parameters":[{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyAuthRequest"},"examples":{"Legacy credentials":{"description":"Authenticate with legacy credentials and create a temporary migration session.","value":{"email":"user@example.com","password":"legacy-account-password"}}}}}},"responses":{"200":{"description":"Organization list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyAuthResponse"},"examples":{"Organizations":{"description":"Legacy organizations available to migrate.","value":{"organizations":[{"id":"legacy_org_abc123","name":"Nebula Systems GmbH","country":"DE","tax_number":"DE112233445","created_at":"2020-05-15T10:00:00.000Z","already_migrated":false,"migrated_environment":null}],"legacy_session_id":"lm_session_abc123"}}}}}},"401":{"description":"Invalid legacy credentials"}}}},"/legacy-migration/jobs":{"post":{"operationId":"createMigrationJob","summary":"Create migration job","description":"Create a new legacy migration job.","security":[{"Bearer":[]}],"tags":["Legacy Migration"],"parameters":[{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"requestBody":{"description":"Migration job details","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMigrationJobRequest"},"examples":{"Start sandbox migration":{"description":"Start a migration into sandbox so the imported data can be reviewed before going live.","value":{"legacy_org_id":"legacy_org_abc123","legacy_session_id":"lm_session_abc123","environment":"sandbox"}},"Confirm unsupported data":{"description":"Start migration after explicitly confirming unsupported legacy data will need manual setup.","value":{"legacy_org_id":"legacy_org_abc123","legacy_session_id":"lm_session_abc123","environment":"live","confirm_unsupported_data":true}}}}}},"responses":{"202":{"description":"Migration job created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMigrationJobResponse"},"examples":{"Created":{"description":"Migration job accepted for background processing.","value":{"id":"mig_507f1f77bcf86cd799439011","status":"pending","message":"Migration job created. It will be processed shortly."}}}}}},"409":{"description":"Active job already exists or entity already migrated (live)"}}},"get":{"operationId":"listMigrationJobs","summary":"List migration jobs","description":"List all migration jobs for the current account.","security":[{"Bearer":[]}],"tags":["Legacy Migration"],"parameters":[{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"Migration jobs list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationJobListResponse"},"examples":{"Pending job":{"description":"List migration jobs for the current account.","value":{"data":[{"id":"mig_507f1f77bcf86cd799439011","legacy_org_id":"legacy_org_abc123","environment":"sandbox","entity_id":null,"status":"pending","step":"Queued","step_number":0,"total_steps":8,"progress_detail":"Migration job is waiting to start.","error":null,"created_at":"2024-01-01T00:00:00.000Z","started_at":null,"completed_at":null}]}}}}}}}}},"/legacy-migration/jobs/{id}":{"get":{"operationId":"getMigrationJob","summary":"Get migration job status","description":"Get status and progress of a migration job.","security":[{"Bearer":[]}],"tags":["Legacy Migration"],"parameters":[{"schema":{"type":"string","description":"Migration job ID"},"required":true,"description":"Migration job ID","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^acc_[0-9a-fA-F]{24}$","description":"Account Id on which the request is made. Optional if user is part of only one account."},"required":false,"description":"Account Id on which the request is made. Optional if user is part of only one account.","name":"x-account-id","in":"header"}],"responses":{"200":{"description":"Migration job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationJobResponse"},"examples":{"Pending":{"description":"Migration job status before processing starts.","value":{"id":"mig_507f1f77bcf86cd799439011","legacy_org_id":"legacy_org_abc123","environment":"sandbox","entity_id":null,"status":"pending","step":"Queued","step_number":0,"total_steps":8,"progress_detail":"Migration job is waiting to start.","error":null,"created_at":"2024-01-01T00:00:00.000Z","started_at":null,"completed_at":null}},"Completed":{"description":"Migration job status after the entity has been created.","value":{"id":"mig_507f1f77bcf86cd799439011","legacy_org_id":"legacy_org_abc123","environment":"sandbox","entity_id":"ent_507f1f77bcf86cd799439011","status":"completed","step":"Completed","step_number":8,"total_steps":8,"progress_detail":"Migration completed successfully.","error":null,"created_at":"2024-01-01T00:00:00.000Z","started_at":"2024-01-01T00:01:00.000Z","completed_at":"2024-01-01T00:07:30.000Z"}}}}}},"404":{"description":"Job not found"}}}}},"webhooks":{}}