{"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":"Customers","description":"Customer management for invoice recipients.\nStore customer details including address and tax information for use in invoice creation."},{"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":"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 invoices and credit notes.\nSupports partial payments, credit note applications to invoices, 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":"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 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":"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":"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":"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":"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 electronically via the Peppol network. Requires supplier onboarding (KYC) before documents can be sent. Currently powered by Flowin (Wolters Kluwer)."}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","description":"Bearer Token Authentication in the form of Authorization: Bearer {token}"}},"schemas":{"DocumentEntity":{"type":"object","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"},"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},"tax_number":{"type":["string","null"]},"tax_number_2":{"type":["string","null"]},"company_number":{"type":["string","null"]},"peppol_id":{"type":["string","null"]},"is_end_consumer":{"type":["boolean","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"},"DocumentCustomer":{"type":["object","null"],"properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"},"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},"tax_number":{"type":["string","null"]},"tax_number_2":{"type":["string","null"]},"company_number":{"type":["string","null"]},"peppol_id":{"type":["string","null"]},"is_end_consumer":{"type":["boolean","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 information"},"DocumentSummaryTax":{"type":"object","properties":{"rate":{"type":["number","null"]},"tax_id":{"type":["string","null"]},"base":{"type":"number"},"amount":{"type":"number"},"reverse_charge":{"type":["boolean","null"]}},"required":["rate","base","amount"]},"ExchangeRate":{"type":["object","null"],"properties":{"rate":{"type":"number","description":"Exchange rate used for conversion"},"source":{"type":"string","description":"Source of the exchange rate (e.g., 'Frankfurter')"},"date":{"type":"string","format":"date-time","description":"Date of the exchange rate"},"quote_currency":{"type":"string","description":"Quote currency (the base currency converted to)"}},"required":["rate","source","date","quote_currency"],"description":"Currency exchange rate information if conversion was applied"},"EslogData":{"type":["object","null"],"properties":{"validation_enabled":{"type":["boolean","null"],"description":"Override entity default: true = validate, false = skip, null = use entity setting"},"validation_status":{"type":["string","null"],"enum":["valid","invalid","not_validated"],"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"}},"description":"e-SLOG 2.0 validation data for Slovenian electronic invoices. Only applicable when entity.country_code = 'SI' and eslog validation is enabled."},"ViesDocumentData":{"type":["object","null"],"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"],"description":"VIES validation info including any warnings and skipped indicator for audit trail"},"FursFiscalizationResponse":{"type":["object","null"],"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},"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"},"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","null"],"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"},"payload":{"type":"object","additionalProperties":{},"description":"CIS SOAP request payload"},"subsequent_submit":{"type":"boolean"},"issuer_oib":{"type":"string"},"operator_label":{"type":"string"}},"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)."},"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"]}},"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},"InvoiceItem":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"type":{"type":["string","null"],"enum":["separator"],"description":"Item type. null = regular line item, 'separator' = visual section header."},"name":{"type":"string","maxLength":500},"description":{"type":["string","null"]},"price":{"type":["number","null"],"description":"Per-unit net price (before tax). Always stores net price. Null for separator items.","example":100},"gross_price":{"type":["number","null"],"description":"Per-unit gross price (includes tax).\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"],"maxLength":50},"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). Applied sequentially to line subtotal.","example":[{"value":10,"type":"percent"}]},"total":{"type":["number","null"],"description":"Line total before tax. Null for separator items.","example":100},"total_with_tax":{"type":["number","null"],"description":"Line total after tax. 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},"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"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","description","taxes","discounts","created_at","updated_at"]},"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"},"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","quote"]},"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"]},"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"},"customer_id":{"type":["string","null"],"maxLength":36},"customer":{"$ref":"#/components/schemas/DocumentCustomer"},"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."},"total":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_with_tax":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_discount":{"type":"number","description":"Total net value of all line-item discounts applied before tax. 0 when no discounts applied."},"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"},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export"],"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":{"$ref":"#/components/schemas/ExchangeRate"},"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 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":{"$ref":"#/components/schemas/EslogData"},"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":{"$ref":"#/components/schemas/ViesDocumentData"},"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":{"$ref":"#/components/schemas/FursFiscalizationResponse"},"fina":{"$ref":"#/components/schemas/FinaFiscalizationResponse"},"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","total","total_with_tax","total_discount","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"},"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."},"CreateDocumentCustomer":{"allOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"type":["object","null"],"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 (matching `tax_number` or `name`) 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 both `customer_id` and `customer` are provided with `save_customer=true`, the existing customer will be updated.\nIf only `customer` is provided with `save_customer=true` (or by default), the system checks for duplicates by `tax_number` or `name`, reusing existing customers when found."},"CreateDocumentItem":{"type":"object","properties":{"type":{"type":["string","null"],"enum":["separator"],"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},"price":{"type":["number","null"],"description":"Net price per unit (before tax).\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 (includes tax).\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"],"maxLength":50},"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). Applied sequentially to line 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"}},"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. If not provided, uses the document total (total_with_tax)"},"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},"CreateFursDocumentData":{"type":["object","null"],"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","null"],"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"],"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"},"subsequent_submit":{"type":["boolean","null"],"description":"Late/subsequent submission flag (NakDost). Set to true if submitting after the normal deadline.","example":false}},"additionalProperties":false},"EslogInput":{"type":["object","null"],"properties":{"validation_enabled":{"type":["boolean","null"],"description":"Enable e-SLOG validation for this document. true = validate, false = skip, null/undefined = use entity default"}}},"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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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"},"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","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."},"furs":{"$ref":"#/components/schemas/CreateFursDocumentData"},"fina":{"$ref":"#/components/schemas/CreateFinaInvoiceData"},"eslog":{"$ref":"#/components/schemas/EslogInput"},"expected_total_with_tax":{"type":"number","exclusiveMinimum":0,"description":"Expected total with tax. 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. Useful when importing invoices from external systems with different rounding rules.","example":122},"force_linked_documents":{"type":"boolean","description":"Force linking documents even if an advance invoice is already applied to another invoice. Defaults to false."}},"required":["items"],"additionalProperties":false},"CustomDocumentItem":{"type":"object","properties":{"type":{"type":["string","null"],"enum":["separator"],"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},"price":{"type":["number","null"],"description":"Net price per unit (before tax). Optional for custom documents. Ignored for separator items.","example":100},"gross_price":{"type":["number","null"],"description":"Gross price per unit (includes tax). 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"],"maxLength":50},"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). Applied sequentially to line subtotal.","example":[{"value":10,"type":"percent"}]},"total":{"type":["number","null"],"description":"Pre-calculated total for this line item (before tax). Ignored for separator items.","example":1000},"total_with_tax":{"type":["number","null"],"description":"Pre-calculated total for this line item (after tax). 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"}},"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},"CustomCreateInvoice":{"type":"object","properties":{"is_draft":{"type":["boolean","null"]},"date":{"type":["string","null"]},"issuer":{"allOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"type":["object","null"]}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"note":{"type":["string","null"]},"payment_terms":{"type":["string","null"]},"tax_clause":{"type":["string","null"]},"footer":{"type":["string","null"]},"signature":{"type":["string","null"]},"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"]},"date_service":{"type":["string","null"]},"date_service_to":{"type":["string","null"]},"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","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."},"furs":{"$ref":"#/components/schemas/CreateFursDocumentData"},"fina":{"$ref":"#/components/schemas/CreateFinaInvoiceData"},"eslog":{"$ref":"#/components/schemas/EslogInput"},"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},"PaginationMetadata":{"type":"object","properties":{"total":{"type":"number","description":"Total number of items available in the collection"},"next_cursor":{"type":["string","null"],"description":"Cursor for fetching the next page. Null if no more results available."},"prev_cursor":{"type":["string","null"],"description":"Cursor for fetching the previous page. 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"},"InvoiceList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"pagination":{"$ref":"#/components/schemas/PaginationMetadata"}},"required":["data","pagination"]},"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."}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Set to null to remove customer reference."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the document. If provided, replaces ALL existing items. Triggers recalculation of totals."},"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."},"signature":{"type":["string","null"],"description":"Signature text (e.g. 'John Smith, CEO'). Set to null to clear."},"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","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":{"$ref":"#/components/schemas/EslogInput"}},"additionalProperties":false},"VersionUser":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":"string"}},"required":["id","name","email"],"description":"User who made the change"},"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":{"$ref":"#/components/schemas/VersionUser"},"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"]},"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"]},"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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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"},"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"}}}},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"minItems":1},"linked_documents":{"type":"array","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"]},"fina":{"$ref":"#/components/schemas/CreateFinaInvoiceData"},"expected_total_with_tax":{"type":"number","exclusiveMinimum":0,"description":"Expected total with tax. 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. Useful when importing invoices from external systems with different rounding rules.","example":122},"force_linked_documents":{"type":"boolean","description":"Force linking documents even if an advance invoice is already applied to another invoice. Defaults to false."}},"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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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"},"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","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"]},"fina":{"$ref":"#/components/schemas/CreateFinaInvoiceData"},"expected_total_with_tax":{"type":"number","exclusiveMinimum":0,"description":"Expected total with tax. 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. Useful when importing invoices from external systems with different rounding rules.","example":122},"force_linked_documents":{"type":"boolean","description":"Force linking documents even if an advance invoice is already applied to another invoice. Defaults to false."}},"required":["items"],"additionalProperties":false},"EstimateItem":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"type":{"type":["string","null"],"enum":["separator"],"description":"Item type. null = regular line item, 'separator' = visual section header."},"name":{"type":"string","maxLength":500},"description":{"type":["string","null"]},"price":{"type":["number","null"],"description":"Per-unit net price (before tax). Always stores net price. Null for separator items.","example":100},"gross_price":{"type":["number","null"],"description":"Per-unit gross price (includes tax).\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"],"maxLength":50},"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). Applied sequentially to line subtotal.","example":[{"value":10,"type":"percent"}]},"total":{"type":["number","null"],"description":"Line total before tax. Null for separator items.","example":100},"total_with_tax":{"type":["number","null"],"description":"Line total after tax. 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},"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"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","description","taxes","discounts","created_at","updated_at"]},"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"},"customer_id":{"type":["string","null"],"maxLength":36},"customer":{"$ref":"#/components/schemas/DocumentCustomer"},"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."},"total":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_with_tax":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_discount":{"type":"number","description":"Total net value of all line-item discounts applied before tax. 0 when no discounts applied."},"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"},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export"],"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":{"$ref":"#/components/schemas/ExchangeRate"},"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 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":{"$ref":"#/components/schemas/EslogData"},"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":{"$ref":"#/components/schemas/ViesDocumentData"},"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_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","quote"],"description":"Display name variant for the document. 'estimate' renders as 'Estimate' (Predračun), 'quote' renders as 'Quote' (Ponudba).","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","total","total_with_tax","total_discount","taxes","currency_code","entity_id","date_year","created_at","updated_at","items"],"description":"Estimate/quote document"},"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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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_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","quote"],"description":"Display name variant for the document. 'estimate' renders as 'Estimate' (Predračun), 'quote' renders as 'Quote' (Ponudba).","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."},"eslog":{"$ref":"#/components/schemas/EslogInput"},"expected_total_with_tax":{"type":"number","exclusiveMinimum":0,"description":"Expected total with tax. 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. 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":{"allOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"type":["object","null"]}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"note":{"type":["string","null"]},"payment_terms":{"type":["string","null"]},"tax_clause":{"type":["string","null"]},"footer":{"type":["string","null"]},"signature":{"type":["string","null"]},"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_valid_till":{"type":["string","null"]},"title_type":{"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"},"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/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."},"eslog":{"$ref":"#/components/schemas/EslogInput"}},"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."}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Set to null to remove customer reference."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the document. If provided, replaces ALL existing items. Triggers recalculation of totals."},"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."},"signature":{"type":["string","null"],"description":"Signature text (e.g. 'John Smith, CEO'). Set to null to clear."},"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","quote"],"description":"Document title type. \"estimate\" or \"quote\".","example":"estimate"},"eslog":{"$ref":"#/components/schemas/EslogInput"}},"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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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_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","quote"],"description":"Display name variant for the document. 'estimate' renders as 'Estimate' (Predračun), 'quote' renders as 'Quote' (Ponudba).","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"}}}},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"minItems":1},"expected_total_with_tax":{"type":"number","exclusiveMinimum":0,"description":"Expected total with tax. 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. Useful when importing invoices from external systems with different rounding rules.","example":122}},"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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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_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","quote"],"description":"Display name variant for the document. 'estimate' renders as 'Estimate' (Predračun), 'quote' renders as 'Quote' (Ponudba).","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."},"expected_total_with_tax":{"type":"number","exclusiveMinimum":0,"description":"Expected total with tax. 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. Useful when importing invoices from external systems with different rounding rules.","example":122}},"required":["items"],"additionalProperties":false},"CreditNoteItem":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"type":{"type":["string","null"],"enum":["separator"],"description":"Item type. null = regular line item, 'separator' = visual section header."},"name":{"type":"string","maxLength":500},"description":{"type":["string","null"]},"price":{"type":["number","null"],"description":"Per-unit net price (before tax). Always stores net price. Null for separator items.","example":100},"gross_price":{"type":["number","null"],"description":"Per-unit gross price (includes tax).\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"],"maxLength":50},"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). Applied sequentially to line subtotal.","example":[{"value":10,"type":"percent"}]},"total":{"type":["number","null"],"description":"Line total before tax. Null for separator items.","example":100},"total_with_tax":{"type":["number","null"],"description":"Line total after tax. 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},"item_id":{"type":["string","null"],"maxLength":36},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","description","taxes","discounts","created_at","updated_at"]},"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"},"customer_id":{"type":["string","null"],"maxLength":36},"customer":{"$ref":"#/components/schemas/DocumentCustomer"},"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."},"total":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_with_tax":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_discount":{"type":"number","description":"Total net value of all line-item discounts applied before tax. 0 when no discounts applied."},"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"},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export"],"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":{"$ref":"#/components/schemas/ExchangeRate"},"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 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":{"$ref":"#/components/schemas/EslogData"},"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":{"$ref":"#/components/schemas/ViesDocumentData"},"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":{"$ref":"#/components/schemas/FursFiscalizationResponse"},"fina":{"$ref":"#/components/schemas/FinaFiscalizationResponse"},"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","total","total_with_tax","total_discount","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"},"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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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_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","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."},"furs":{"$ref":"#/components/schemas/CreateFursDocumentData"},"fina":{"$ref":"#/components/schemas/CreateFinaInvoiceData"},"eslog":{"$ref":"#/components/schemas/EslogInput"},"expected_total_with_tax":{"type":"number","exclusiveMinimum":0,"description":"Expected total with tax. 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. 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":{"allOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"type":["object","null"]}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"note":{"type":["string","null"]},"payment_terms":{"type":["string","null"]},"tax_clause":{"type":["string","null"]},"footer":{"type":["string","null"]},"signature":{"type":["string","null"]},"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_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"},"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","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."},"furs":{"$ref":"#/components/schemas/CreateFursDocumentData"},"fina":{"$ref":"#/components/schemas/CreateFinaInvoiceData"},"eslog":{"$ref":"#/components/schemas/EslogInput"}},"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."}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Set to null to remove customer reference."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the document. If provided, replaces ALL existing items. Triggers recalculation of totals."},"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."},"signature":{"type":["string","null"],"description":"Signature text (e.g. 'John Smith, CEO'). Set to null to clear."},"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","items":{"type":"string","minLength":1},"description":"Link this credit note to invoices. Replaces existing links. Accepts invoice IDs (inv_xxx).","example":["inv_abc123"]},"eslog":{"$ref":"#/components/schemas/EslogInput"}},"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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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_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"}}}},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"minItems":1},"linked_documents":{"type":"array","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"]},"fina":{"$ref":"#/components/schemas/CreateFinaInvoiceData"},"expected_total_with_tax":{"type":"number","exclusiveMinimum":0,"description":"Expected total with tax. 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. Useful when importing invoices from external systems with different rounding rules.","example":122}},"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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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_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","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"]},"fina":{"$ref":"#/components/schemas/CreateFinaInvoiceData"},"expected_total_with_tax":{"type":"number","exclusiveMinimum":0,"description":"Expected total with tax. 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. Useful when importing invoices from external systems with different rounding rules.","example":122}},"required":["items"],"additionalProperties":false},"AdvanceInvoiceItem":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"type":{"type":["string","null"],"enum":["separator"],"description":"Item type. null = regular line item, 'separator' = visual section header."},"name":{"type":"string","maxLength":500},"description":{"type":["string","null"]},"price":{"type":["number","null"],"description":"Per-unit net price (before tax). Always stores net price. Null for separator items.","example":100},"gross_price":{"type":["number","null"],"description":"Per-unit gross price (includes tax).\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"],"maxLength":50},"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). Applied sequentially to line subtotal.","example":[{"value":10,"type":"percent"}]},"total":{"type":["number","null"],"description":"Line total before tax. Null for separator items.","example":100},"total_with_tax":{"type":["number","null"],"description":"Line total after tax. 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},"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"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","description","taxes","discounts","created_at","updated_at"]},"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"},"customer_id":{"type":["string","null"],"maxLength":36},"customer":{"$ref":"#/components/schemas/DocumentCustomer"},"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."},"total":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_with_tax":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_discount":{"type":"number","description":"Total net value of all line-item discounts applied before tax. 0 when no discounts applied."},"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"},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export"],"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":{"$ref":"#/components/schemas/ExchangeRate"},"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 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":{"$ref":"#/components/schemas/EslogData"},"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":{"$ref":"#/components/schemas/ViesDocumentData"},"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":{"$ref":"#/components/schemas/FursFiscalizationResponse"},"fina":{"$ref":"#/components/schemas/FinaFiscalizationResponse"},"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","total","total_with_tax","total_discount","taxes","currency_code","entity_id","date_year","created_at","updated_at","total_paid","total_due","paid_in_full","items"],"description":"Advance invoice for prepayments"},"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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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"},"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","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."},"furs":{"$ref":"#/components/schemas/CreateFursDocumentData"},"fina":{"$ref":"#/components/schemas/CreateFinaInvoiceData"},"expected_total_with_tax":{"type":"number","exclusiveMinimum":0,"description":"Expected total with tax. 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. 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":{"allOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"type":["object","null"]}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"note":{"type":["string","null"]},"tax_clause":{"type":["string","null"]},"footer":{"type":["string","null"]},"signature":{"type":["string","null"]},"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"],"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/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","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."},"furs":{"$ref":"#/components/schemas/CreateFursDocumentData"},"fina":{"$ref":"#/components/schemas/CreateFinaInvoiceData"}},"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."}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Set to null to remove customer reference."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the document. If provided, replaces ALL existing items. Triggers recalculation of totals."},"note":{"type":["string","null"],"description":"Document note/memo. Set to null to clear."},"signature":{"type":["string","null"],"description":"Signature text (e.g. 'John Smith, CEO'). Set to null to clear."},"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","items":{"type":"string","minLength":1},"description":"Link this advance invoice to other documents. Replaces existing links. Accepts invoice IDs (inv_xxx).","example":["inv_abc123"]}},"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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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"},"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"}}}},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"minItems":1},"linked_documents":{"type":"array","items":{"type":"string","minLength":1},"description":"Link this advance invoice to other documents. Creates document relations automatically.","example":[]},"fina":{"$ref":"#/components/schemas/CreateFinaInvoiceData"},"expected_total_with_tax":{"type":"number","exclusiveMinimum":0,"description":"Expected total with tax. 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. Useful when importing invoices from external systems with different rounding rules.","example":122}},"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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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"},"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","items":{"type":"string","minLength":1},"description":"Link this advance invoice to other documents. Creates document relations automatically.","example":[]},"fina":{"$ref":"#/components/schemas/CreateFinaInvoiceData"},"expected_total_with_tax":{"type":"number","exclusiveMinimum":0,"description":"Expected total with tax. 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. Useful when importing invoices from external systems with different rounding rules.","example":122}},"required":["items"],"additionalProperties":false},"DeliveryNoteItem":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"type":{"type":["string","null"],"enum":["separator"],"description":"Item type. null = regular line item, 'separator' = visual section header."},"name":{"type":"string","maxLength":500},"description":{"type":["string","null"]},"price":{"type":["number","null"],"description":"Per-unit net price (before tax). Always stores net price. Null for separator items.","example":100},"gross_price":{"type":["number","null"],"description":"Per-unit gross price (includes tax).\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"],"maxLength":50},"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). Applied sequentially to line subtotal.","example":[{"value":10,"type":"percent"}]},"total":{"type":["number","null"],"description":"Line total before tax. Null for separator items.","example":100},"total_with_tax":{"type":["number","null"],"description":"Line total after tax. 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},"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"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","description","taxes","discounts","created_at","updated_at"]},"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"},"customer_id":{"type":["string","null"],"maxLength":36},"customer":{"$ref":"#/components/schemas/DocumentCustomer"},"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."},"total":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_with_tax":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"total_discount":{"type":"number","description":"Total net value of all line-item discounts applied before tax. 0 when no discounts applied."},"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"},"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c","export"],"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":{"$ref":"#/components/schemas/ExchangeRate"},"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 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":{"$ref":"#/components/schemas/EslogData"},"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":{"$ref":"#/components/schemas/ViesDocumentData"},"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","total","total_with_tax","total_discount","taxes","currency_code","entity_id","date_year","created_at","updated_at","hide_prices","items"],"description":"Delivery note / packing list document"},"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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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":{"$ref":"#/components/schemas/EslogInput"},"linked_documents":{"type":"array","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","exclusiveMinimum":0,"description":"Expected total with tax. 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. 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":{"allOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"type":["object","null"]}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"note":{"type":["string","null"]},"payment_terms":{"type":["string","null"]},"tax_clause":{"type":["string","null"]},"footer":{"type":["string","null"]},"signature":{"type":["string","null"]},"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"},"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","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"]},"eslog":{"$ref":"#/components/schemas/EslogInput"}},"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."}]},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Set to null to remove customer reference."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CreateDocumentItem"},"minItems":1,"description":"Line items for the document. If provided, replaces ALL existing items. Triggers recalculation of totals."},"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."},"signature":{"type":["string","null"],"description":"Signature text (e.g. 'John Smith, CEO'). Set to null to clear."},"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","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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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"}}}},"metadata":{"type":"object","additionalProperties":{"type":"string"}}}},"minItems":1},"linked_documents":{"type":"array","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","exclusiveMinimum":0,"description":"Expected total with tax. 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. Useful when importing invoices from external systems with different rounding rules.","example":122}},"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"},"customer_id":{"type":["string","null"],"description":"Referenced Customer ID. Required if customer is not provided."},"customer":{"$ref":"#/components/schemas/CreateDocumentCustomer"},"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."},"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."},"linked_documents":{"type":"array","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","exclusiveMinimum":0,"description":"Expected total with tax. 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. Useful when importing invoices from external systems with different rounding rules.","example":122}},"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."}},"required":["number"]},"CalculatedItem":{"type":"object","properties":{"name":{"type":["string","null"]},"description":{"type":["string","null"]},"type":{"type":["string","null"],"enum":["separator"]},"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"]},"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"]},"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":"Total net value of all line-item discounts applied before tax"},"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"],"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":{"allOf":[{"$ref":"#/components/schemas/ExchangeRate"},{"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":{"$ref":"#/components/schemas/ViesDocumentData"}},"required":["items","total","total_with_tax","total_discount","taxes","transaction_type","currency_code","exchange_rate","total_converted","total_with_tax_converted","rounding_correction","vies"]},"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":{"allOf":[{"$ref":"#/components/schemas/DocumentEntity"},{"type":["object","null"],"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 (matching `tax_number` or `name`) 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 data. Used for transaction type determination (country-based VAT rules)."},"customer_id":{"type":["string","null"],"description":"Existing customer ID. Alternative to inline customer data."},"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"},"expected_total_with_tax":{"type":"number","exclusiveMinimum":0,"description":"Expected total with tax. 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. Useful when importing invoices from external systems with different rounding rules.","example":122}},"required":["items"]},"GenericDocument":{},"FinalizeDocumentBody":{"type":"object","properties":{"furs":{"$ref":"#/components/schemas/CreateFursDocumentData"},"fina":{"$ref":"#/components/schemas/CreateFinaInvoiceData"}}},"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"]},"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"]}]},"EntityApiKeysList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EntityApiKeyListItem"}}},"required":["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"},"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"},"StatsQueryBatchResponse":{"type":"array","items":{"$ref":"#/components/schemas/StatsQueryResponse"},"description":"Array of stats query responses, in same order as requests"},"StatsFilters":{"type":"object","additionalProperties":{},"description":"Additional filters (field: value pairs)","example":{"is_draft":false,"voided_at":null}},"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"},"StatsQueryBatchRequest":{"type":"array","items":{"$ref":"#/components/schemas/StatsQueryRequest"},"minItems":1,"maxItems":25,"description":"Array of stats query requests (1-25 queries per batch)"},"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"]},"EntityUsersList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EntityUser"}}},"required":["data"]},"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"},"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"},"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"]},"EntityInvitationsList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EntityInvitation"}}},"required":["data"]},"ResendInvitationResponse":{"type":"object","properties":{"message":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}},"required":["message","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"]},"TaxRules":{"type":["object","null"],"properties":{"eu":{"type":["object","null"],"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 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 (VIES validation, reverse charge, export tax removal). Defaults are set automatically based on entity country. Set to null for non-EU entities."},"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}}},"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"},"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},"tax_number":{"type":["string","null"],"maxLength":50},"tax_number_2":{"type":["string","null"],"maxLength":50},"company_number":{"type":["string","null"],"maxLength":50},"email":{"type":["string","null"],"maxLength":255},"website":{"type":["string","null"],"maxLength":500},"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"],"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"]}}},"primary_color":{"type":["string","null"],"pattern":"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"},"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_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":"Dear {customer_name},\n\nPlease find your invoice attached."},"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":"Dear {customer_name},\n\nPlease find your estimate attached."},"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":"Dear {customer_name},\n\nPlease find your credit note 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":"Dear {customer_name},\n\nPlease find your advance invoice 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":"Dear {customer_name},\n\nPlease find your delivery note 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":"Net 30 days. Payment due by {document_due_date}."},"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}"},"slovenia":{"type":["object","null"],"properties":{"business_form":{"type":["string","null"],"enum":["sp","doo","dno","club"],"description":"Stored Slovenian legal form for country-specific exports and reporting.","example":"sp"},"income_tax_regime":{"type":["string","null"],"enum":["normirani","dejanski"],"description":"Stored Slovenian income tax regime for yearly reporting.","example":"normirani"},"vat_profile":{"type":["string","null"],"enum":["standard","special_vat_identified"],"description":"Stored Slovenian VAT subject subtype.","example":"standard"},"tax_residency":{"type":["string","null"],"enum":["resident","non_resident"],"description":"Stored Slovenian tax residency status.","example":"resident"},"yearly_reporting":{"type":["object","null"],"properties":{"activity_code":{"type":["string","null"],"maxLength":10,"description":"Primary Slovenian SKD activity code used for yearly reporting.","example":"62.010"},"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"],"description":"Bookkeeping / records mode used in the yearly filing.","example":"records"},"normiranec_insurance_basis":{"type":["string","null"],"enum":["full_time_self_employed","other"],"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}},"description":"Slovenia-specific yearly reporting defaults and profile data."}},"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},"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."},"tax_rules":{"$ref":"#/components/schemas/TaxRules"},"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"],"description":"Custom email subject. Available variables: {customer_name}, {entity_name}, {overdue_count}","example":"Payment Reminder: Overdue invoice(s) from {entity_name}"},"email_body":{"type":["string","null"],"description":"Custom email body. Available variables: {customer_name}, {entity_name}, {invoice_list}, {total_amount}, {entity_email}. If {invoice_list} is not included, the invoice table will be auto-appended.","example":"Dear {customer_name},\n\nThis is a friendly reminder about your overdue invoices."}},"description":"Settings for automatic overdue invoice notification emails to customers"},"upn_qr":{"type":["object","null"],"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"],"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."},"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},"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 prices and totals as negative values. Set to false to show all values as positive.","example":true},"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":{"type":["object","null"],"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."}},"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":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Whether e-invoicing is enabled for this entity. Requires supplier onboarding to be completed before documents can be sent.","example":true},"provider":{"type":"string","enum":["flowin"],"default":"flowin","description":"E-invoicing provider. Currently only Flowin (Wolters Kluwer) is supported.","example":"flowin"},"auto_send":{"type":"boolean","default":false,"description":"Automatically send invoices via e-invoice after creation. Only works when entity is fully onboarded with the provider.","example":false},"default_scheme_id":{"type":"string","description":"Default Peppol participant scheme ID for this entity. Common values: \"0009\" (SIRET, France), \"9925\" (VAT, Belgium), \"0088\" (EAN/GLN).","example":"0009"}},"description":"E-invoicing settings for sending documents via Peppol network (through Flowin). Requires supplier onboarding before documents can be sent electronically."}},"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."},"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"],"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"],"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","description":"Start date filter (ISO 8601 date). Date range cannot exceed 1 year.","example":"2024-01-01"},"date_to":{"type":"string","description":"End date filter (ISO 8601 date). Date range cannot exceed 1 year.","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"],"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"],"description":"Override PDF label language. When omitted or null, defaults to the locale language, then entity locale.","example":"de"}},"required":["types"]},"Item":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"name":{"type":"string","maxLength":500},"description":{"type":["string","null"],"maxLength":2000},"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},"tax_ids":{"type":"array","items":{"type":"string","maxLength":36}},"total_tax":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"entity_id":{"type":"string","maxLength":36},"metadata":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}},{"type":"null"}]},"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","tax_ids","total_tax","entity_id","metadata","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},"amount":{"type":"number","minimum":-140737488355328,"maximum":140737488355327},"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"}},"required":["id","amount","currency_code","amount_converted","type","date","entity_id","created_at","updated_at"],"description":"Payment record for an invoice, credit note, or advance invoice"},"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"},"entity_id":{"type":"string","maxLength":36},"metadata":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}},{"type":"null"}]},"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"},"FileMetadataBase":{"type":"object","properties":{"id":{"type":"string","maxLength":36},"entity_id":{"type":"string","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},"category":{"type":"string","maxLength":20},"url":{"type":"string","maxLength":500},"secureUrl":{"type":"string","maxLength":500},"publicId":{"type":"string","maxLength":200},"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":{}},{"type":"null"}]},"cache_key":{"type":["string","null"],"maxLength":255},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","entity_id","category","url","secureUrl","publicId","format","bytes","mime_type","metadata","created_at","updated_at"],"description":"File metadata record with upload information"},"FileMetadata":{"allOf":[{"$ref":"#/components/schemas/FileMetadataBase"},{"type":"object","properties":{}}],"description":"File metadata record with upload information"},"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":{}},{"type":"null"}]},"metadata":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}},{"type":"null"}]},"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"]},"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},"email":{"type":["string","null"],"maxLength":255},"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":{}},{"type":"null"}]},"metadata":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"object","additionalProperties":{}},{"type":"array","items":{}},{"type":"null"}]},"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","is_tax_subject","is_end_consumer","entity_id","metadata","created_at","updated_at"],"description":"Customer information"},"Customer":{"allOf":[{"$ref":"#/components/schemas/CustomerBase"},{"type":"object","properties":{}}],"description":"Customer of the Entity"},"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","e_invoicing.submission.created","e_invoicing.submission.delivered","e_invoicing.submission.failed","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","e_invoicing.submission.created","e_invoicing.submission.delivered","e_invoicing.submission.failed","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"},"RealEstatePremise":{"type":["object","null"],"properties":{"property_id":{"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"]},"cadastral_number":{"type":"string"}},"required":["property_id","building_number","building_section","community","street","house_number","house_number_additional","cadastral_number"]},"MovablePremise":{"type":["object","null"],"properties":{"type":{"type":"string"}},"required":["type"]},"FursElectronicDevice":{"type":"object","properties":{"id":{"type":"string"},"business_premise_id":{"type":"string"},"electronic_device_name":{"type":"string"},"is_active":{"type":"boolean"},"registered_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","business_premise_id","electronic_device_name","is_active","registered_at","created_at","updated_at"]},"FursBusinessPremise":{"type":"object","properties":{"id":{"type":"string"},"entity_id":{"type":"string"},"business_premise_name":{"type":"string"},"type":{"type":"string"},"real_estate":{"$ref":"#/components/schemas/RealEstatePremise"},"movable_premise":{"$ref":"#/components/schemas/MovablePremise"},"is_active":{"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","registered_at","closed_at","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"]},"FinaRealEstatePremise":{"type":["object","null"],"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","null"],"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"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","premise_id","electronic_device_name","is_active","created_at","updated_at"]},"FinaBusinessPremise":{"type":"object","properties":{"id":{"type":"string"},"entity_id":{"type":"string"},"business_premise_name":{"type":"string"},"type":{"type":"string"},"real_estate":{"$ref":"#/components/schemas/FinaRealEstatePremise"},"movable_premise":{"$ref":"#/components/schemas/FinaMovablePremise"},"is_active":{"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","registered_at","closed_at","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"]},"TransactionTypeCheckResponse":{"type":"object","properties":{"transaction_type":{"type":["string","null"],"enum":["domestic","intra_eu_b2b","intra_eu_b2c","3w_b2b","3w_b2c"],"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"]},"EInvoicingSettingsResponse":{"type":"object","properties":{"enabled":{"type":"boolean"},"provider":{"type":"string"},"auto_send":{"type":"boolean"},"default_scheme_id":{"type":"string"}},"required":["enabled","provider","auto_send"],"description":"Current e-invoicing settings for the entity"},"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 invoices via e-invoice after creation","example":false},"default_scheme_id":{"type":"string","maxLength":10,"description":"Default Peppol participant scheme ID","example":"0009"}},"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},"flowin_supplier_id":{"type":["string","null"],"maxLength":255},"provider":{"type":"string","maxLength":50},"status":{"type":"string","maxLength":50},"reject_reason":{"type":["string","null"]},"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","provider","status","company_name","country_code","created_at","updated_at"],"description":"E-invoicing supplier registration (Flowin/Peppol onboarding status)"},"RegisterEInvoicingSupplierRequest":{"type":"object","properties":{"company_name":{"type":"string","minLength":1,"maxLength":255,"description":"Legal company name as registered","example":"Acme SAS"},"vat_number":{"type":"string","maxLength":50,"description":"VAT identification number","example":"FR12345678901"},"company_number":{"type":"string","maxLength":50,"description":"Company registration number (e.g., SIRET for France)","example":"12345678901234"},"iban":{"type":"string","maxLength":50,"description":"Bank account IBAN","example":"FR7630006000011234567890189"},"address":{"type":"string","maxLength":500,"description":"Street address","example":"123 Rue de la Paix"},"city":{"type":"string","maxLength":100,"description":"City","example":"Paris"},"post_code":{"type":"string","maxLength":20,"description":"Postal code","example":"75001"},"country_code":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code","example":"FR"},"contact_email":{"type":"string","maxLength":255,"format":"email","description":"Contact email for KYC communication","example":"billing@acme.fr"},"contact_phone":{"type":"string","maxLength":50,"description":"Contact phone number","example":"+33612345678"}},"required":["company_name","country_code"],"additionalProperties":false,"description":"Register a supplier for e-invoicing onboarding (starts KYC process)"},"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":"Update supplier onboarding data"},"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":"Peppol customer search result"},"EInvoicingCustomerSearchRequest":{"type":"object","properties":{"peppol_id":{"type":"string","minLength":1,"description":"Peppol participant ID to search for","example":"FR12345678901234"},"scheme_id":{"type":"string","minLength":1,"maxLength":10,"description":"Peppol scheme ID","example":"0009"}},"required":["peppol_id","scheme_id"],"additionalProperties":false,"description":"Search for a customer on the Peppol network"},"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},"flowin_document_id":{"type":["string","null"],"maxLength":255},"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 (document sent via Peppol)"},"SendEInvoiceRequest":{"type":"object","properties":{"recipient_peppol_id":{"type":"string","minLength":1,"description":"Recipient's Peppol participant ID","example":"0009:98765432109876"},"recipient_scheme_id":{"type":"string","minLength":1,"maxLength":10,"description":"Recipient's Peppol scheme ID","example":"0009"},"recipient_name":{"type":"string","maxLength":255,"description":"Recipient name (for display purposes)","example":"Client Corp SARL"}},"required":["recipient_peppol_id","recipient_scheme_id"],"additionalProperties":false,"description":"Send a document as an e-invoice via Peppol"},"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},"flowin_document_id":{"type":["string","null"],"maxLength":255},"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 (includes UBL XML)"},"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"]},"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"},"CompanyRegistrySearchResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CompanyRegistryResult"}}},"required":["data"]},"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"},"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":{}},{"type":"null"}]},"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"},"RecurringInvoice":{"allOf":[{"$ref":"#/components/schemas/RecurringInvoiceBase"},{"type":"object","properties":{}}],"description":"Recurring invoice schedule"},"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"},"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"]},"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."},"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"}},"required":["slug","name","hidden_features","hal_app_id","support_email"],"description":"White-label configuration for the current domain","example":{"slug":"space-invoices","name":"Space Invoices","hidden_features":[],"theme":null,"hal_app_id":null,"support_email":null}},"PlanLimits":{"type":["object","null"],"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}},"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"]},"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},"limits":{"$ref":"#/components/schemas/PlanLimits"},"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","limits","features","is_free","display_order"],"description":"A subscription plan for a white-label product"},"StoreBilling":{"type":["object","null"],"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},"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"},"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"},"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},"cancel_at":{"type":["string","null"],"description":"Scheduled cancellation date (ISO 8601). Null if not scheduled.","example":null},"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":{"$ref":"#/components/schemas/StoreBilling"},"usage":{"$ref":"#/components/schemas/UsageStats"}},"required":["plan","status","billing_interval","current_period_start","current_period_end","trial_ends_at","trial_days_remaining","cancel_at","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},"features":["invoices","estimates","customers","items","pdf_export","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","trial_ends_at":null,"trial_days_remaining":null,"cancel_at":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,"period_start":"2025-01-01T00:00:00.000Z","period_end":"2025-01-31T23:59:59.999Z"}}},"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"}},"required":["plans","current_plan_slug"],"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","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}},"ShopifyAuthorizeResponse":{"type":"object","properties":{"redirect_url":{"type":"string","format":"uri"}},"required":["redirect_url"]},"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"},"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_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":{}},{"type":"null"}]},"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","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"},"OrderIntegration":{"allOf":[{"$ref":"#/components/schemas/OrderIntegrationBase"},{"type":"object","properties":{}}],"description":"Order Integration"},"OrderCustomer":{"type":["object","null"],"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","null"],"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"},"sku":{"type":"string"},"source_id":{"type":"string"},"discount":{"type":"number"},"unit":{"type":"string"}},"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","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":{"$ref":"#/components/schemas/OrderCustomer"},"billing_address":{"$ref":"#/components/schemas/OrderAddress"},"shipping_address":{"$ref":"#/components/schemas/OrderAddress"},"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":{}},{"type":"null"}]},"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","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"},"Order":{"allOf":[{"$ref":"#/components/schemas/OrderBase"},{"type":"object","properties":{}}],"description":"Order"},"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"]}}},"required":["organizations"]},"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"},"environment":{"type":"string","enum":["live","sandbox"],"description":"Target environment","example":"sandbox"}},"required":["legacy_org_id","environment"],"additionalProperties":false},"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"]},"MigrationJobListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MigrationJobResponse"}}},"required":["data"]}},"parameters":{}},"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,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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.\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"}],"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":"Cosmo Forschung 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 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 Starfield"},"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 partial payment":{"value":{"items":[{"name":"Professional Services","quantity":1,"price":1500}],"payments":[{"type":"cash","amount":500}]},"description":"Invoice with partial payment - shows amount still due"},"With payment":{"value":{"items":[{"name":"Professional Services","quantity":1,"price":1500}],"payments":[{"type":"bank_transfer"}]},"description":"Invoice with payment - marks invoice as paid in full"},"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","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","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","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,"item_id":null,"name":"Satellite Communication Module","description":null,"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,"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,"item_id":null,"name":"Thermal Shielding Panel","description":null,"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,"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,"item_id":null,"name":"Orbital Navigation License","description":null,"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,"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,"item_id":null,"name":"EVA Toolkit - Standard","description":null,"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,"item_id":null,"name":"Orbital Navigation License","description":null,"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,"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,"item_id":null,"name":"Satellite Communication Module","description":null,"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,"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,"item_id":null,"name":"Satellite Communication Module","description":null,"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,"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,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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","-id","-number","-date","-total","-total_with_tax","-created_at","-updated_at","-date_due"]},{"type":"array","items":{"type":"string","enum":["id","number","date","total","total_with_tax","created_at","updated_at","date_due","-id","-number","-date","-total","-total_with_tax","-created_at","-updated_at","-date_due"]}}]},"required":false,"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, 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_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, 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_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,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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":"Create an invoice with pre-calculated totals from an external ERP or accounting system.\nThe caller provides `total`, `total_with_tax`, and `taxes` at the document level, and `total`/`total_with_tax` on each line item.\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"}],"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,"item_id":null,"name":"Satellite Communication Module","description":null,"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,"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,"item_id":null,"name":"Thermal Shielding Panel","description":null,"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,"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,"item_id":null,"name":"Orbital Navigation License","description":null,"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,"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,"item_id":null,"name":"EVA Toolkit - Standard","description":null,"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,"item_id":null,"name":"Orbital Navigation License","description":null,"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,"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,"item_id":null,"name":"Satellite Communication Module","description":null,"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,"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,"item_id":null,"name":"Satellite Communication Module","description":null,"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,"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,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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":"Web Development","quantity":40,"price":125},{"name":"Hosting - Annual","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,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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}/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,"item_id":null,"name":"Satellite Communication Module","description":null,"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,"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":"John Doe","email":"john@example.com"},"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,"item_id":null,"name":"Satellite Communication Module","description":null,"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,"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":"John Doe","email":"john@example.com"},"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,"item_id":null,"name":"Satellite Communication Module","description":null,"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,"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":"John Doe","email":"john@example.com"},"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","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"}}},"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","description":"Manually fiscalize an invoice that was created before FURS was enabled. Auto-creates a dedicated \"OLD\" premise and device for FURS submission, assigns a new sequential FURS number (OLD-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":"OLD","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,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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":{"post":{"operationId":"createEstimate","summary":"Create a new estimate","description":"Create a new estimate with line items.\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"}],"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":"Cosmo Forschung 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 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 Starfield"},"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."},"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","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","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","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,"item_id":null,"name":"Satellite Communication Module","description":null,"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,"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,"item_id":null,"name":"Thermal Shielding Panel","description":null,"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,"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,"item_id":null,"name":"Orbital Navigation License","description":null,"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,"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,"item_id":null,"name":"EVA Toolkit - Standard","description":null,"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,"item_id":null,"name":"Orbital Navigation License","description":null,"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,"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,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"]}}]},"required":false,"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, 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, 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,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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":"Create an estimate with pre-calculated totals from an external system.\nThe caller provides `total`, `total_with_tax`, and `taxes` at the document level, and `total`/`total_with_tax` on each line item.\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"}],"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,"item_id":null,"name":"Satellite Communication Module","description":null,"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,"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,"item_id":null,"name":"Thermal Shielding Panel","description":null,"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,"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,"item_id":null,"name":"Orbital Navigation License","description":null,"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,"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,"item_id":null,"name":"EVA Toolkit - Standard","description":null,"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,"item_id":null,"name":"Orbital Navigation License","description":null,"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,"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,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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":"Web Development","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,"item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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,"item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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,"item_id":null,"name":"Satellite Communication Module","description":null,"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,"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":"John Doe","email":"john@example.com"},"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,"item_id":null,"name":"Satellite Communication Module","description":null,"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,"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":"John Doe","email":"john@example.com"},"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,"item_id":null,"name":"Satellite Communication Module","description":null,"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,"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":"John Doe","email":"john@example.com"},"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","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.\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"}],"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"},"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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"]}}]},"required":false,"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, 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, 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- `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":"Create a credit note with pre-calculated totals from an external system.\nThe caller provides `total`, `total_with_tax`, and `taxes` at the document level, and `total`/`total_with_tax` on each line item.\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"}],"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}/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":"John Doe","email":"john@example.com"},"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":"John Doe","email":"john@example.com"},"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":"John Doe","email":"john@example.com"},"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","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}/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"}}},"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","item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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","item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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":{"post":{"operationId":"createAdvanceInvoice","summary":"Create a new advance invoice","description":"Create a new advance invoice with line items. Advance 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"}],"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","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","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","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","item_id":null,"name":"Satellite Communication Module","description":null,"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,"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","item_id":null,"name":"Thermal Shielding Panel","description":null,"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,"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","item_id":null,"name":"EVA Toolkit - Standard","description":null,"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","item_id":null,"name":"Orbital Navigation License","description":null,"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,"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","item_id":null,"name":"Satellite Communication Module","description":null,"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,"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","item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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","item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"]}}]},"required":false,"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, 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\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, 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\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","item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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","item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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":"Create an advance invoice with pre-calculated totals from an external system.\nThe caller provides `total`, `total_with_tax`, and `taxes` at the document level, and `total`/`total_with_tax` on each line item.\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"}],"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","item_id":null,"name":"Satellite Communication Module","description":null,"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,"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","item_id":null,"name":"Thermal Shielding Panel","description":null,"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,"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","item_id":null,"name":"EVA Toolkit - Standard","description":null,"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","item_id":null,"name":"Orbital Navigation License","description":null,"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,"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","item_id":null,"name":"Satellite Communication Module","description":null,"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,"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","item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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","item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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","item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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","item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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","item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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","item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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","item_id":null,"name":"Satellite Communication Module","description":null,"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,"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":"John Doe","email":"john@example.com"},"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","item_id":null,"name":"Satellite Communication Module","description":null,"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,"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":"John Doe","email":"john@example.com"},"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","item_id":null,"name":"Satellite Communication Module","description":null,"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,"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":"John Doe","email":"john@example.com"},"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","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"}}},"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","item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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","item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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.\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"}],"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":"Cosmo Forschung 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 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 Starfield"},"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."},"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","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","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","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","item_id":null,"name":"Satellite Communication Module","description":null,"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,"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","item_id":null,"name":"Thermal Shielding Panel","description":null,"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,"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","item_id":null,"name":"Orbital Navigation License","description":null,"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,"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","item_id":null,"name":"EVA Toolkit - Standard","description":null,"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","item_id":null,"name":"Orbital Navigation License","description":null,"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,"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","item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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","item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"]}}]},"required":false,"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, 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, 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","item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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","item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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":"Create a delivery note with pre-calculated totals from an external system.\nThe caller provides `total`, `total_with_tax`, and `taxes` at the document level, and `total`/`total_with_tax` on each line item.\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"}],"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","item_id":null,"name":"Satellite Communication Module","description":null,"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,"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","item_id":null,"name":"Thermal Shielding Panel","description":null,"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,"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","item_id":null,"name":"Orbital Navigation License","description":null,"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,"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","item_id":null,"name":"EVA Toolkit - Standard","description":null,"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","item_id":null,"name":"Orbital Navigation License","description":null,"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,"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","item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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","item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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","item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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","item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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":"Web Development","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","item_id":null,"name":"Ground Station Antenna Array","description":"Deep space tracking antenna with 12m dish","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","item_id":null,"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","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.","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","item_id":null,"name":"Satellite Communication Module","description":null,"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,"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":"John Doe","email":"john@example.com"},"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","item_id":null,"name":"Satellite Communication Module","description":null,"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,"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":"John Doe","email":"john@example.com"},"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","item_id":null,"name":"Satellite Communication Module","description":null,"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,"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":"John Doe","email":"john@example.com"},"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","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":"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":{"Basic":{"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":{"Basic":{"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 retry fiscalization for a document that has a failed fiscalization status. Only documents with failed FURS or FINA fiscalization can be retried.","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":"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}":{"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}},"required":["to"],"additionalProperties":false},"examples":{"Basic":{"value":{"to":"customer@example.com"}},"WithOptions":{"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"],"description":"Email send status","example":"sent"},"to":{"type":"string","format":"email","description":"Recipient email address","example":"customer@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..."}},"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/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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"]}}]},"required":false,"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":"user@example.com","details":{"to":"customer@example.com","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":"user@example.com","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}}}}}},"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"}}}},"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"}}}}},"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"}}}}},"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":"John Admin","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":"Jane Editor","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 user to the entity or send an invitation to a new user. If the user exists, they are immediately granted access. If not, an invitation email is sent.","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)"}}}}},"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":"New User","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/{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":"Jane Editor","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"}}}},"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 an access token for a WL user to enable SSO-like redirect. This allows account admins to redirect users to the web app without requiring them to login.","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":"John Doe","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":"John Doe","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"}}}},"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/accept":{"post":{"operationId":"acceptEntityInvitation","summary":"Accept invitation","description":"Accept an entity invitation by providing user details. Creates a new user 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","minLength":1,"maxLength":255,"description":"Name of the user accepting the invitation","example":"John Doe"},"password":{"type":"string","minLength":8,"description":"Password for the new user account","example":"securepassword123"}},"required":["name","password"],"additionalProperties":false},"example":{"Accept with signup":{"description":"Accept invitation and create account","value":{"token":"abc123def456","name":"John Doe","password":"SecurePass123!"}}}}}},"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","maxLength":20},"tax_number":{"type":["string","null"],"maxLength":50},"tax_number_2":{"type":["string","null"],"maxLength":50},"company_number":{"type":["string","null"],"maxLength":50},"email":{"type":["string","null"],"maxLength":255},"website":{"type":["string","null"],"maxLength":500},"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"],"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"]}}},"primary_color":{"type":["string","null"],"pattern":"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"},"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_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":"Dear {customer_name},\n\nPlease find your invoice attached."},"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":"Dear {customer_name},\n\nPlease find your estimate attached."},"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":"Dear {customer_name},\n\nPlease find your credit note 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":"Dear {customer_name},\n\nPlease find your advance invoice 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":"Dear {customer_name},\n\nPlease find your delivery note 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":"Net 30 days. Payment due by {document_due_date}."},"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}"},"slovenia":{"type":["object","null"],"properties":{"business_form":{"type":["string","null"],"enum":["sp","doo","dno","club"],"description":"Stored Slovenian legal form for country-specific exports and reporting.","example":"sp"},"income_tax_regime":{"type":["string","null"],"enum":["normirani","dejanski"],"description":"Stored Slovenian income tax regime for yearly reporting.","example":"normirani"},"vat_profile":{"type":["string","null"],"enum":["standard","special_vat_identified"],"description":"Stored Slovenian VAT subject subtype.","example":"standard"},"tax_residency":{"type":["string","null"],"enum":["resident","non_resident"],"description":"Stored Slovenian tax residency status.","example":"resident"},"yearly_reporting":{"type":["object","null"],"properties":{"activity_code":{"type":["string","null"],"maxLength":10,"description":"Primary Slovenian SKD activity code used for yearly reporting.","example":"62.010"},"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"],"description":"Bookkeeping / records mode used in the yearly filing.","example":"records"},"normiranec_insurance_basis":{"type":["string","null"],"enum":["full_time_self_employed","other"],"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}},"description":"Slovenia-specific yearly reporting defaults and profile data."}},"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},"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."},"tax_rules":{"$ref":"#/components/schemas/TaxRules"},"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"],"description":"Custom email subject. Available variables: {customer_name}, {entity_name}, {overdue_count}","example":"Payment Reminder: Overdue invoice(s) from {entity_name}"},"email_body":{"type":["string","null"],"description":"Custom email body. Available variables: {customer_name}, {entity_name}, {invoice_list}, {total_amount}, {entity_email}. If {invoice_list} is not included, the invoice table will be auto-appended.","example":"Dear {customer_name},\n\nThis is a friendly reminder about your overdue invoices."}},"description":"Settings for automatic overdue invoice notification emails to customers"},"upn_qr":{"type":["object","null"],"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"],"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."},"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},"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 prices and totals as negative values. Set to false to show all values as positive.","example":true},"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":{"type":["object","null"],"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."}},"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":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Whether e-invoicing is enabled for this entity. Requires supplier onboarding to be completed before documents can be sent.","example":true},"provider":{"type":"string","enum":["flowin"],"default":"flowin","description":"E-invoicing provider. Currently only Flowin (Wolters Kluwer) is supported.","example":"flowin"},"auto_send":{"type":"boolean","default":false,"description":"Automatically send invoices via e-invoice after creation. Only works when entity is fully onboarded with the provider.","example":false},"default_scheme_id":{"type":"string","description":"Default Peppol participant scheme ID for this entity. Common values: \"0009\" (SIRET, France), \"9925\" (VAT, Belgium), \"0088\" (EAN/GLN).","example":"0009"}},"description":"E-invoicing settings for sending documents via Peppol network (through Flowin). Requires supplier onboarding before documents can be sent electronically."}},"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":"Beispiel 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."},"Complete":{"value":{"name":"Space Invoices d.o.o.","address":"Tehnološki park 24","address_2":"Building A","post_code":"1000","city":"Ljubljana","country":"Slovenia","tax_number":"SI12345678","company_number":"1234567000","metadata":{"industry":"Technology","size":"Medium"}},"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":"CN-{yyyy}-{nnnnn}","delivery_note":"DN-{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Invoice {document_number} from {entity_name}","invoice_body":"Dear {customer_name},\n\nThank you for your business! Please find your invoice {document_number} attached.\n\nInvoice Details:\n- Invoice Number: {document_number}\n- Invoice Date: {document_date}\n- Due Date: {document_due_date}\n- Total Amount: {document_total} {document_currency}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}","estimate_subject":"Estimate {document_number} from {entity_name}","estimate_body":"Dear {customer_name},\n\nThank you for your interest! Please find your estimate {document_number} attached.\n\nEstimate Details:\n- Estimate Number: {document_number}\n- Estimate Date: {document_date}\n- Valid Until: {document_valid_until}\n- Total Amount: {document_total} {document_currency}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}","credit_note_subject":"Credit note {document_number} from {entity_name}","credit_note_body":"Dear {customer_name},\n\nPlease find your credit note {document_number} attached.\n\nCredit Note Details:\n- Credit Note Number: {document_number}\n- Date: {document_date}\n- Total Amount: {document_total} {document_currency}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}","advance_invoice_subject":"Advance invoice {document_number} from {entity_name}","advance_invoice_body":"Dear {customer_name},\n\nPlease find your advance invoice {document_number} attached.\n\nAdvance Invoice Details:\n- Advance Invoice Number: {document_number}\n- Date: {document_date}\n- Total Amount: {document_total} {document_currency}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}","delivery_note_subject":"Delivery note {document_number} from {entity_name}","delivery_note_body":"Dear {customer_name},\n\nPlease find your delivery note {document_number} attached.\n\nDelivery Note Details:\n- Delivery Note Number: {document_number}\n- Date: {document_date}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}"},"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: Overdue invoice(s) from {entity_name}","email_body":"Dear {customer_name},\n\nThis is a friendly reminder that you have overdue invoices from {entity_name}.\n\n{invoice_list}\n\nPlease review and pay at your earliest convenience.\n\nIf you have any questions, please contact us at {entity_email}.\n\nBest regards,\n{entity_name}"},"tax_rules":null},"account_id":"acc_6595a27b5d35015c3ef0c3fd","metadata":{},"country_rules":{"max_taxes_per_item":3,"features":[]},"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":"Beispiel 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":"CN-{yyyy}-{nnnnn}","delivery_note":"DN-{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Rechnung {document_number} von {entity_name}","invoice_body":"Sehr geehrte/r {customer_name},\n\nvielen Dank für Ihren Auftrag! Anbei finden Sie Ihre Rechnung {document_number}.\n\nRechnungsdetails:\n- Rechnungsnummer: {document_number}\n- Rechnungsdatum: {document_date}\n- Fälligkeitsdatum: {document_due_date}\n- Gesamtbetrag: {document_total} {document_currency}\n\nBei Fragen kontaktieren Sie uns bitte unter {entity_email}.\n\nMit freundlichen Grüßen,\n{entity_name}","estimate_subject":"Angebot {document_number} von {entity_name}","estimate_body":"Sehr geehrte/r {customer_name},\n\nvielen Dank für Ihr Interesse! Anbei finden Sie Ihr Angebot {document_number}.\n\nAngebotsdetails:\n- Angebotsnummer: {document_number}\n- Angebotsdatum: {document_date}\n- Gültig bis: {document_valid_until}\n- Gesamtbetrag: {document_total} {document_currency}\n\nBei Fragen kontaktieren Sie uns bitte unter {entity_email}.\n\nMit freundlichen Grüßen,\n{entity_name}","credit_note_subject":"Gutschrift {document_number} von {entity_name}","credit_note_body":"Sehr geehrte/r {customer_name},\n\nanbei finden Sie Ihre Gutschrift {document_number}.\n\nGutschriftdetails:\n- Gutschriftnummer: {document_number}\n- Datum: {document_date}\n- Gesamtbetrag: {document_total} {document_currency}\n\nBei Fragen kontaktieren Sie uns bitte unter {entity_email}.\n\nMit freundlichen Grüßen,\n{entity_name}","advance_invoice_subject":"Vorausrechnung {document_number} von {entity_name}","advance_invoice_body":"Sehr geehrte/r {customer_name},\n\nanbei finden Sie Ihre Vorausrechnung {document_number}.\n\nVorausrechnungsdetails:\n- Vorausrechnungsnummer: {document_number}\n- Datum: {document_date}\n- Gesamtbetrag: {document_total} {document_currency}\n\nBei Fragen kontaktieren Sie uns bitte unter {entity_email}.\n\nMit freundlichen Grüßen,\n{entity_name}","delivery_note_subject":"Lieferschein {document_number} von {entity_name}","delivery_note_body":"Sehr geehrte/r {customer_name},\n\nanbei finden Sie Ihren Lieferschein {document_number}.\n\nLieferscheindetails:\n- Lieferscheinnummer: {document_number}\n- Datum: {document_date}\n\nBei Fragen kontaktieren Sie uns bitte unter {entity_email}.\n\nMit freundlichen Grüßen,\n{entity_name}"},"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: Überfällige Rechnung(en) von {entity_name}","email_body":"Sehr geehrte/r {customer_name},\n\ndies ist eine freundliche Erinnerung, dass Sie überfällige Rechnungen von {entity_name} haben.\n\n{invoice_list}\n\nBitte überprüfen und begleichen Sie diese so bald wie möglich.\n\nBei Fragen kontaktieren Sie uns bitte unter {entity_email}.\n\nMit freundlichen Grüßen,\n{entity_name}"},"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":["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."},"Complete":{"value":{"id":"ent_7595a27b5d35015c3ef0c3fe","name":"Space Invoices d.o.o.","address":"Tehnološki park 24","address_2":"Building A","post_code":"1000","city":"Ljubljana","state":null,"country":"Slovenia","country_code":"SI","currency_code":"EUR","locale":"sl-SI","tax_number":"SI12345678","tax_number_2":null,"company_number":"1234567000","email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":true,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"CN-{yyyy}-{nnnnn}","delivery_note":"DN-{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Račun {document_number} od {entity_name}","invoice_body":"Spoštovani {customer_name},\n\nzahvaljujemo se vam za zaupanje! V priponki vam pošiljamo račun {document_number}.\n\nPodrobnosti računa:\n- Številka računa: {document_number}\n- Datum računa: {document_date}\n- Rok plačila: {document_due_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","estimate_subject":"Predračun {document_number} od {entity_name}","estimate_body":"Spoštovani {customer_name},\n\nzahvaljujemo se vam za povpraševanje! V priponki vam pošiljamo predračun {document_number}.\n\nPodrobnosti predračuna:\n- Številka predračuna: {document_number}\n- Datum predračuna: {document_date}\n- Veljavnost do: {document_valid_until}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","credit_note_subject":"Dobropis {document_number} od {entity_name}","credit_note_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo dobropis {document_number}.\n\nPodrobnosti dobropisa:\n- Številka dobropisa: {document_number}\n- Datum: {document_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","advance_invoice_subject":"Avansni račun {document_number} od {entity_name}","advance_invoice_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo avansni račun {document_number}.\n\nPodrobnosti avansnega računa:\n- Številka avansnega računa: {document_number}\n- Datum: {document_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","delivery_note_subject":"Dobavnica {document_number} od {entity_name}","delivery_note_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo dobavnico {document_number}.\n\nPodrobnosti dobavnice:\n- Številka dobavnice: {document_number}\n- Datum: {document_date}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}"},"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":"Opomin za plačilo: Zapadli račun(i) od {entity_name}","email_body":"Spoštovani {customer_name},\n\nto je prijazni opomin, da imate zapadle račune od {entity_name}.\n\n{invoice_list}\n\nProsimo, preglejte in poravnajte zapadle obveznosti čim prej.\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}"},"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":{"industry":"Technology","size":"Medium"},"country_rules":{"max_taxes_per_item":1,"features":["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":"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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"]}}]},"required":false,"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":"Space Invoices d.o.o.","address":"Tehnološki park 24","address_2":"Building A","post_code":"1000","city":"Ljubljana","state":null,"country":"Slovenia","country_code":"SI","currency_code":"EUR","locale":"sl-SI","tax_number":"SI12345678","tax_number_2":null,"company_number":"1234567000","email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":true,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"CN-{yyyy}-{nnnnn}","delivery_note":"DN-{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Račun {document_number} od {entity_name}","invoice_body":"Spoštovani {customer_name},\n\nzahvaljujemo se vam za zaupanje! V priponki vam pošiljamo račun {document_number}.\n\nPodrobnosti računa:\n- Številka računa: {document_number}\n- Datum računa: {document_date}\n- Rok plačila: {document_due_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","estimate_subject":"Predračun {document_number} od {entity_name}","estimate_body":"Spoštovani {customer_name},\n\nzahvaljujemo se vam za povpraševanje! V priponki vam pošiljamo predračun {document_number}.\n\nPodrobnosti predračuna:\n- Številka predračuna: {document_number}\n- Datum predračuna: {document_date}\n- Veljavnost do: {document_valid_until}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","credit_note_subject":"Dobropis {document_number} od {entity_name}","credit_note_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo dobropis {document_number}.\n\nPodrobnosti dobropisa:\n- Številka dobropisa: {document_number}\n- Datum: {document_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","advance_invoice_subject":"Avansni račun {document_number} od {entity_name}","advance_invoice_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo avansni račun {document_number}.\n\nPodrobnosti avansnega računa:\n- Številka avansnega računa: {document_number}\n- Datum: {document_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","delivery_note_subject":"Dobavnica {document_number} od {entity_name}","delivery_note_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo dobavnico {document_number}.\n\nPodrobnosti dobavnice:\n- Številka dobavnice: {document_number}\n- Datum: {document_date}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}"},"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":"Opomin za plačilo: Zapadli račun(i) od {entity_name}","email_body":"Spoštovani {customer_name},\n\nto je prijazni opomin, da imate zapadle račune od {entity_name}.\n\n{invoice_list}\n\nProsimo, preglejte in poravnajte zapadle obveznosti čim prej.\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}"},"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":{"industry":"Technology","size":"Medium"},"country_rules":{"max_taxes_per_item":1,"features":["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"}],"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":"Space Invoices d.o.o.","address":"Tehnološki park 24","address_2":"Building A","post_code":"1000","city":"Ljubljana","state":null,"country":"Slovenia","country_code":"SI","currency_code":"EUR","locale":"sl-SI","tax_number":"SI12345678","tax_number_2":null,"company_number":"1234567000","email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":true,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"CN-{yyyy}-{nnnnn}","delivery_note":"DN-{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Račun {document_number} od {entity_name}","invoice_body":"Spoštovani {customer_name},\n\nzahvaljujemo se vam za zaupanje! V priponki vam pošiljamo račun {document_number}.\n\nPodrobnosti računa:\n- Številka računa: {document_number}\n- Datum računa: {document_date}\n- Rok plačila: {document_due_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","estimate_subject":"Predračun {document_number} od {entity_name}","estimate_body":"Spoštovani {customer_name},\n\nzahvaljujemo se vam za povpraševanje! V priponki vam pošiljamo predračun {document_number}.\n\nPodrobnosti predračuna:\n- Številka predračuna: {document_number}\n- Datum predračuna: {document_date}\n- Veljavnost do: {document_valid_until}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","credit_note_subject":"Dobropis {document_number} od {entity_name}","credit_note_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo dobropis {document_number}.\n\nPodrobnosti dobropisa:\n- Številka dobropisa: {document_number}\n- Datum: {document_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","advance_invoice_subject":"Avansni račun {document_number} od {entity_name}","advance_invoice_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo avansni račun {document_number}.\n\nPodrobnosti avansnega računa:\n- Številka avansnega računa: {document_number}\n- Datum: {document_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","delivery_note_subject":"Dobavnica {document_number} od {entity_name}","delivery_note_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo dobavnico {document_number}.\n\nPodrobnosti dobavnice:\n- Številka dobavnice: {document_number}\n- Datum: {document_date}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}"},"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":"Opomin za plačilo: Zapadli račun(i) od {entity_name}","email_body":"Spoštovani {customer_name},\n\nto je prijazni opomin, da imate zapadle račune od {entity_name}.\n\n{invoice_list}\n\nProsimo, preglejte in poravnajte zapadle obveznosti čim prej.\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}"},"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":{"industry":"Technology","size":"Medium"},"country_rules":{"max_taxes_per_item":1,"features":["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":"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. 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","maxLength":20},"tax_number":{"type":["string","null"],"maxLength":50},"tax_number_2":{"type":["string","null"],"maxLength":50},"company_number":{"type":["string","null"],"maxLength":50},"email":{"type":["string","null"],"maxLength":255},"website":{"type":["string","null"],"maxLength":500},"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"],"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"]}}},"primary_color":{"type":["string","null"],"pattern":"^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"},"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_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":"Dear {customer_name},\n\nPlease find your invoice attached."},"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":"Dear {customer_name},\n\nPlease find your estimate attached."},"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":"Dear {customer_name},\n\nPlease find your credit note 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":"Dear {customer_name},\n\nPlease find your advance invoice 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":"Dear {customer_name},\n\nPlease find your delivery note 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":"Net 30 days. Payment due by {document_due_date}."},"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}"},"slovenia":{"type":["object","null"],"properties":{"business_form":{"type":["string","null"],"enum":["sp","doo","dno","club"],"description":"Stored Slovenian legal form for country-specific exports and reporting.","example":"sp"},"income_tax_regime":{"type":["string","null"],"enum":["normirani","dejanski"],"description":"Stored Slovenian income tax regime for yearly reporting.","example":"normirani"},"vat_profile":{"type":["string","null"],"enum":["standard","special_vat_identified"],"description":"Stored Slovenian VAT subject subtype.","example":"standard"},"tax_residency":{"type":["string","null"],"enum":["resident","non_resident"],"description":"Stored Slovenian tax residency status.","example":"resident"},"yearly_reporting":{"type":["object","null"],"properties":{"activity_code":{"type":["string","null"],"maxLength":10,"description":"Primary Slovenian SKD activity code used for yearly reporting.","example":"62.010"},"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"],"description":"Bookkeeping / records mode used in the yearly filing.","example":"records"},"normiranec_insurance_basis":{"type":["string","null"],"enum":["full_time_self_employed","other"],"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}},"description":"Slovenia-specific yearly reporting defaults and profile data."}},"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},"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."},"tax_rules":{"$ref":"#/components/schemas/TaxRules"},"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"],"description":"Custom email subject. Available variables: {customer_name}, {entity_name}, {overdue_count}","example":"Payment Reminder: Overdue invoice(s) from {entity_name}"},"email_body":{"type":["string","null"],"description":"Custom email body. Available variables: {customer_name}, {entity_name}, {invoice_list}, {total_amount}, {entity_email}. If {invoice_list} is not included, the invoice table will be auto-appended.","example":"Dear {customer_name},\n\nThis is a friendly reminder about your overdue invoices."}},"description":"Settings for automatic overdue invoice notification emails to customers"},"upn_qr":{"type":["object","null"],"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"],"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."},"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},"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 prices and totals as negative values. Set to false to show all values as positive.","example":true},"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":{"type":["object","null"],"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."}},"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":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false,"description":"Whether e-invoicing is enabled for this entity. Requires supplier onboarding to be completed before documents can be sent.","example":true},"provider":{"type":"string","enum":["flowin"],"default":"flowin","description":"E-invoicing provider. Currently only Flowin (Wolters Kluwer) is supported.","example":"flowin"},"auto_send":{"type":"boolean","default":false,"description":"Automatically send invoices via e-invoice after creation. Only works when entity is fully onboarded with the provider.","example":false},"default_scheme_id":{"type":"string","description":"Default Peppol participant scheme ID for this entity. Common values: \"0009\" (SIRET, France), \"9925\" (VAT, Belgium), \"0088\" (EAN/GLN).","example":"0009"}},"description":"E-invoicing settings for sending documents via Peppol network (through Flowin). Requires supplier onboarding before documents can be sent electronically."}},"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"}}},"additionalProperties":false},"examples":{"Update name":{"value":{"name":"Updated Company Name"},"description":"Update entity name"},"Update address":{"value":{"address":"Dunajska cesta 100","city":"Ljubljana","post_code":"1000"},"description":"Update entity address details"}}}}},"responses":{"200":{"description":"Updated Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Entity"},"examples":{"Update name":{"value":{"id":"ent_6595a27b5d35015c3ef0c3fd","name":"Updated Company Name","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":"CN-{yyyy}-{nnnnn}","delivery_note":"DN-{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Invoice {document_number} from {entity_name}","invoice_body":"Dear {customer_name},\n\nThank you for your business! Please find your invoice {document_number} attached.\n\nInvoice Details:\n- Invoice Number: {document_number}\n- Invoice Date: {document_date}\n- Due Date: {document_due_date}\n- Total Amount: {document_total} {document_currency}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}","estimate_subject":"Estimate {document_number} from {entity_name}","estimate_body":"Dear {customer_name},\n\nThank you for your interest! Please find your estimate {document_number} attached.\n\nEstimate Details:\n- Estimate Number: {document_number}\n- Estimate Date: {document_date}\n- Valid Until: {document_valid_until}\n- Total Amount: {document_total} {document_currency}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}","credit_note_subject":"Credit note {document_number} from {entity_name}","credit_note_body":"Dear {customer_name},\n\nPlease find your credit note {document_number} attached.\n\nCredit Note Details:\n- Credit Note Number: {document_number}\n- Date: {document_date}\n- Total Amount: {document_total} {document_currency}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}","advance_invoice_subject":"Advance invoice {document_number} from {entity_name}","advance_invoice_body":"Dear {customer_name},\n\nPlease find your advance invoice {document_number} attached.\n\nAdvance Invoice Details:\n- Advance Invoice Number: {document_number}\n- Date: {document_date}\n- Total Amount: {document_total} {document_currency}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}","delivery_note_subject":"Delivery note {document_number} from {entity_name}","delivery_note_body":"Dear {customer_name},\n\nPlease find your delivery note {document_number} attached.\n\nDelivery Note Details:\n- Delivery Note Number: {document_number}\n- Date: {document_date}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}"},"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: Overdue invoice(s) from {entity_name}","email_body":"Dear {customer_name},\n\nThis is a friendly reminder that you have overdue invoices from {entity_name}.\n\n{invoice_list}\n\nPlease review and pay at your earliest convenience.\n\nIf you have any questions, please contact us at {entity_email}.\n\nBest regards,\n{entity_name}"},"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"}},"account_id":"acc_6595a27b5d35015c3ef0c3fd","metadata":{},"country_rules":{"max_taxes_per_item":1,"features":["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":"Space Invoices 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":"CN-{yyyy}-{nnnnn}","delivery_note":"DN-{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Invoice {document_number} from {entity_name}","invoice_body":"Dear {customer_name},\n\nThank you for your business! Please find your invoice {document_number} attached.\n\nInvoice Details:\n- Invoice Number: {document_number}\n- Invoice Date: {document_date}\n- Due Date: {document_due_date}\n- Total Amount: {document_total} {document_currency}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}","estimate_subject":"Estimate {document_number} from {entity_name}","estimate_body":"Dear {customer_name},\n\nThank you for your interest! Please find your estimate {document_number} attached.\n\nEstimate Details:\n- Estimate Number: {document_number}\n- Estimate Date: {document_date}\n- Valid Until: {document_valid_until}\n- Total Amount: {document_total} {document_currency}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}","credit_note_subject":"Credit note {document_number} from {entity_name}","credit_note_body":"Dear {customer_name},\n\nPlease find your credit note {document_number} attached.\n\nCredit Note Details:\n- Credit Note Number: {document_number}\n- Date: {document_date}\n- Total Amount: {document_total} {document_currency}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}","advance_invoice_subject":"Advance invoice {document_number} from {entity_name}","advance_invoice_body":"Dear {customer_name},\n\nPlease find your advance invoice {document_number} attached.\n\nAdvance Invoice Details:\n- Advance Invoice Number: {document_number}\n- Date: {document_date}\n- Total Amount: {document_total} {document_currency}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}","delivery_note_subject":"Delivery note {document_number} from {entity_name}","delivery_note_body":"Dear {customer_name},\n\nPlease find your delivery note {document_number} attached.\n\nDelivery Note Details:\n- Delivery Note Number: {document_number}\n- Date: {document_date}\n\nIf you have any questions, please don't hesitate to contact us at {entity_email}.\n\nBest regards,\n{entity_name}"},"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: Overdue invoice(s) from {entity_name}","email_body":"Dear {customer_name},\n\nThis is a friendly reminder that you have overdue invoices from {entity_name}.\n\n{invoice_list}\n\nPlease review and pay at your earliest convenience.\n\nIf you have any questions, please contact us at {entity_email}.\n\nBest regards,\n{entity_name}"},"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":["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":"Space Invoices d.o.o.","address":"Tehnološki park 24","address_2":"Building A","post_code":"1000","city":"Ljubljana","state":null,"country":"Slovenia","country_code":"SI","currency_code":"EUR","locale":"sl-SI","tax_number":"SI12345678","tax_number_2":null,"company_number":"1234567000","email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":true,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"CN-{yyyy}-{nnnnn}","delivery_note":"DN-{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Račun {document_number} od {entity_name}","invoice_body":"Spoštovani {customer_name},\n\nzahvaljujemo se vam za zaupanje! V priponki vam pošiljamo račun {document_number}.\n\nPodrobnosti računa:\n- Številka računa: {document_number}\n- Datum računa: {document_date}\n- Rok plačila: {document_due_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","estimate_subject":"Predračun {document_number} od {entity_name}","estimate_body":"Spoštovani {customer_name},\n\nzahvaljujemo se vam za povpraševanje! V priponki vam pošiljamo predračun {document_number}.\n\nPodrobnosti predračuna:\n- Številka predračuna: {document_number}\n- Datum predračuna: {document_date}\n- Veljavnost do: {document_valid_until}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","credit_note_subject":"Dobropis {document_number} od {entity_name}","credit_note_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo dobropis {document_number}.\n\nPodrobnosti dobropisa:\n- Številka dobropisa: {document_number}\n- Datum: {document_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","advance_invoice_subject":"Avansni račun {document_number} od {entity_name}","advance_invoice_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo avansni račun {document_number}.\n\nPodrobnosti avansnega računa:\n- Številka avansnega računa: {document_number}\n- Datum: {document_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","delivery_note_subject":"Dobavnica {document_number} od {entity_name}","delivery_note_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo dobavnico {document_number}.\n\nPodrobnosti dobavnice:\n- Številka dobavnice: {document_number}\n- Datum: {document_date}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}"},"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":"Opomin za plačilo: Zapadli račun(i) od {entity_name}","email_body":"Spoštovani {customer_name},\n\nto je prijazni opomin, da imate zapadle račune od {entity_name}.\n\n{invoice_list}\n\nProsimo, preglejte in poravnajte zapadle obveznosti čim prej.\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}"},"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":{"industry":"Technology","size":"Medium"},"country_rules":{"max_taxes_per_item":1,"features":["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"}}}},"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":"Space Invoices d.o.o.","address":"Tehnološki park 24","address_2":"Building A","post_code":"1000","city":"Ljubljana","state":null,"country":"Slovenia","country_code":"SI","currency_code":"EUR","locale":"sl-SI","tax_number":"SI12345678","tax_number_2":null,"company_number":"1234567000","email":null,"website":null,"environment":"live","is_tax_subject":true,"is_enabled":false,"settings":{"number_formats":{"invoice":"{yyyy}-{nnnnn}","estimate":"{yyyy}-{nnnnn}","credit_note":"CN-{yyyy}-{nnnnn}","delivery_note":"DN-{yyyy}-{nnnnn}"},"email_defaults":{"invoice_subject":"Račun {document_number} od {entity_name}","invoice_body":"Spoštovani {customer_name},\n\nzahvaljujemo se vam za zaupanje! V priponki vam pošiljamo račun {document_number}.\n\nPodrobnosti računa:\n- Številka računa: {document_number}\n- Datum računa: {document_date}\n- Rok plačila: {document_due_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","estimate_subject":"Predračun {document_number} od {entity_name}","estimate_body":"Spoštovani {customer_name},\n\nzahvaljujemo se vam za povpraševanje! V priponki vam pošiljamo predračun {document_number}.\n\nPodrobnosti predračuna:\n- Številka predračuna: {document_number}\n- Datum predračuna: {document_date}\n- Veljavnost do: {document_valid_until}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","credit_note_subject":"Dobropis {document_number} od {entity_name}","credit_note_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo dobropis {document_number}.\n\nPodrobnosti dobropisa:\n- Številka dobropisa: {document_number}\n- Datum: {document_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","advance_invoice_subject":"Avansni račun {document_number} od {entity_name}","advance_invoice_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo avansni račun {document_number}.\n\nPodrobnosti avansnega računa:\n- Številka avansnega računa: {document_number}\n- Datum: {document_date}\n- Skupni znesek: {document_total} {document_currency}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}","delivery_note_subject":"Dobavnica {document_number} od {entity_name}","delivery_note_body":"Spoštovani {customer_name},\n\nv priponki vam pošiljamo dobavnico {document_number}.\n\nPodrobnosti dobavnice:\n- Številka dobavnice: {document_number}\n- Datum: {document_date}\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}"},"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":"Opomin za plačilo: Zapadli račun(i) od {entity_name}","email_body":"Spoštovani {customer_name},\n\nto je prijazni opomin, da imate zapadle račune od {entity_name}.\n\n{invoice_list}\n\nProsimo, preglejte in poravnajte zapadle obveznosti čim prej.\n\nZa vprašanja nas kontaktirajte na {entity_email}.\n\nLep pozdrav,\n{entity_name}"},"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":{"industry":"Technology","size":"Medium"},"country_rules":{"max_taxes_per_item":1,"features":["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"}}}},"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/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":true,"description":"Document type to export","name":"type","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","enum":["en","de","sl","it","fr","es","pt","nl","pl","hr","sv","fi","et","bg","cs","sk","nb","is"],"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","enum":["en","de","sl","it","fr","es","pt","nl","pl","hr","sv","fi","et","bg","cs","sk","nb","is"],"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)"}}}}},"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 percentage (0-100)","example":50},"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}},"required":["id","status","progress","total_docs","file_url","file_name","error"]},"examples":{"inProgress":{"value":{"id":"expjob_clx1234567890","status":"processing","progress":50,"total_docs":25,"file_url":null,"file_name":"acme_documents_2024-06-01_2024-06-30.zip","error":null},"summary":"Export job in progress"}}}}},"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":{"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},"price":{"type":"number","description":"Net price per unit (before tax). Provide either price OR gross_price, not both.","example":100},"gross_price":{"type":"number","description":"Gross price per unit (includes tax). If provided, net price is calculated. Provide either price OR gross_price, not both.","example":122},"tax_ids":{"type":"array","items":{"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"}},"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 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"},"Complete":{"value":{"name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","price":5000,"taxes":[{"rate":22}],"metadata":{"category":"software","unit":"license"}},"description":"Item with all optional fields"}}}}},"responses":{"201":{"description":"Created Item","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Item"},{"type":"object","properties":{}}],"description":"Item or Service provided to customers by the Entity"},"examples":{"Minimal":{"value":{"id":"item_6595a27b5d35015c3ef0c3fd","name":"Satellite Communication Module","description":null,"price":1500,"gross_price":null,"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,"price":2200,"gross_price":null,"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,"price":12500,"gross_price":null,"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,"price":850,"gross_price":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"},"Complete":{"value":{"id":"item_7595a27b5d35015c3ef0c3fe","name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","price":5000,"gross_price":null,"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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"]}}]},"required":false,"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":{"allOf":[{"$ref":"#/components/schemas/Item"},{"allOf":[{"$ref":"#/components/schemas/Item"},{"type":"object","properties":{}}],"description":"Item or Service provided to customers by the Entity"}]}},"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","price":5000,"gross_price":null,"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},"price":{"type":"number","description":"Net price per unit (before tax). Provide either price OR gross_price, not both.","example":100},"gross_price":{"type":"number","description":"Gross price per unit (includes tax). If provided, net price is calculated. Provide either price OR gross_price, not both.","example":122},"tax_ids":{"type":"array","items":{"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"}},"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":{"allOf":[{"$ref":"#/components/schemas/Item"},{"allOf":[{"$ref":"#/components/schemas/Item"},{"type":"object","properties":{}}],"description":"Item or Service provided to customers by the Entity"}]},"examples":{"Minimal":{"value":{"id":"item_6595a27b5d35015c3ef0c3fd","name":"Satellite Communication Module v2","description":null,"price":1500,"gross_price":null,"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,"price":900,"gross_price":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"}}}},"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":{"allOf":[{"$ref":"#/components/schemas/Item"},{"allOf":[{"$ref":"#/components/schemas/Item"},{"type":"object","properties":{}}],"description":"Item or Service provided to customers by the Entity"}]},"examples":{"Minimal":{"value":{"id":"item_6595a27b5d35015c3ef0c3fd","name":"Satellite Communication Module","description":null,"price":1500,"gross_price":null,"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,"price":2200,"gross_price":null,"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,"price":12500,"gross_price":null,"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,"price":850,"gross_price":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"},"Complete":{"value":{"id":"item_7595a27b5d35015c3ef0c3fe","name":"Orbital Navigation License","description":"Annual software license for orbital trajectory planning","price":5000,"gross_price":null,"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"}}}},"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 invoice, credit note, or both.\nAt least one document reference is required.\nFor type `credit_note`, both `invoice_id` and `credit_note_id` are required (applying credit to invoice).\nDocument payment totals are automatically updated.\nCredit note payments cannot exceed the credit note total.","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},"amount":{"type":"number","exclusiveMinimum":0},"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"}}},"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"},"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"},"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,"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,"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,"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,"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,"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"}}}}}},"get":{"operationId":"getPayments","summary":"List all payments","description":"Retrieve a paginated list of payments with optional filtering and sorting. Supports cursor-based pagination for efficient navigation, flexible JSON querying with MongoDB-style operators, full-text search, and sorting by various payment properties.","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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"]}}]},"required":false,"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, 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, 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\n**Usage:**\n`?include=Invoice`\n`?include=Invoice,CreditNote,AdvanceInvoice`","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\n**Usage:**\n`?include=Invoice`\n`?include=Invoice,CreditNote,AdvanceInvoice`","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,"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,"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\n**Usage:**\n`?include=Invoice`\n`?include=Invoice,CreditNote,AdvanceInvoice`","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\n**Usage:**\n`?include=Invoice`\n`?include=Invoice,CreditNote,AdvanceInvoice`","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,"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 documents are automatically recalculated.","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},"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 documents (invoice, credit note) are automatically recalculated after deletion.","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"}}}},"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,"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"}}}},"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"}},"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"},"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)"},"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":{"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"},"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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"]}}]},"required":false,"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":{"allOf":[{"$ref":"#/components/schemas/Tax"},{"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"}]}},"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"}},"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":{"allOf":[{"$ref":"#/components/schemas/Tax"},{"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"}]},"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"}},"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"},"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":{"allOf":[{"$ref":"#/components/schemas/Tax"},{"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"}]},"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"}}}},"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":{"allOf":[{"$ref":"#/components/schemas/Tax"},{"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"}]},"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"}}}},"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://res.cloudinary.com/demo/image/upload/v1234567890/si/logos/entity-logo.png"},"secureUrl":{"type":"string","format":"uri","description":"Secure HTTPS URL of the uploaded image","example":"https://res.cloudinary.com/demo/image/upload/v1234567890/si/logos/entity-logo.png"},"publicId":{"type":"string","description":"Cloudinary public ID for future reference/deletion","example":"si/logos/entity-logo"},"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":"http://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011.png","secureUrl":"https://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011.png","publicId":"si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011","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"}},"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":"http://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011.png","secureUrl":"https://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011.png","publicId":"si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011","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":"http://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011.png","secureUrl":"https://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011.png","publicId":"si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011","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":"http://res.cloudinary.com/demo/raw/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890.pdf","secureUrl":"https://res.cloudinary.com/demo/raw/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890.pdf","publicId":"si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890","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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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","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":"http://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011.png","secureUrl":"https://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011.png","publicId":"si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011","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":"http://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011.png","secureUrl":"https://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011.png","publicId":"si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011","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":"http://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011.png","secureUrl":"https://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011.png","publicId":"si/entities/ent_507f1f77bcf86cd799439011/signatures/signature_ent_507f1f77bcf86cd799439011","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":"http://res.cloudinary.com/demo/raw/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890.pdf","secureUrl":"https://res.cloudinary.com/demo/raw/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890.pdf","publicId":"si/entities/ent_507f1f77bcf86cd799439011/attachments/attachment_1234567890","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/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","enum":["en","de","sl","it","fr","es","pt","nl","pl","hr","sv","fi","et","bg","cs","sk","nb","is"],"description":"Preferred UI language","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/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":"John Doe"}}}}}},"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"}}}}}}},"/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},"email":{"type":["string","null"],"maxLength":255},"is_tax_subject":{"type":"boolean"},"is_end_consumer":{"type":["boolean","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 Starfield"},"description":"Minimal customer with only required fields"},"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 Starfield","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,"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.com","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,"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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"]}}]},"required":false,"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, 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, 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 Starfield","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,"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.com","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,"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},"email":{"type":["string","null"],"maxLength":255},"is_tax_subject":{"type":"boolean"},"is_end_consumer":{"type":["boolean","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.com","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,"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"}}}},"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.com","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,"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"}}}},"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","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 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, defaults to appending 'View your invoice online: {url}' at the bottom.","example":"Please find your invoice attached.\n\nAccess it online: {invoice_link}"},"document_id":{"type":"string","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},"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"],"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 Acme Corp 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"},"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- Professional consulting services (120 hours)\n- Technical 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 Acme Corp, 123 Business Ave, City, ST 12345\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**Acme Corp 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"],"description":"Email send status","example":"sent"},"to":{"type":"string","format":"email","description":"Recipient email address","example":"customer@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..."}},"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 Acme Corp","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","e_invoicing.submission.created","e_invoicing.submission.delivered","e_invoicing.submission.failed","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"},"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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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","e_invoicing.submission.created","e_invoicing.submission.delivered","e_invoicing.submission.failed","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"}}}}},"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"}}}},"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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"}}}}}}},"/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"},"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","has_certificate"]},"examples":{"Configured Settings":{"value":{"enabled":true,"numbering_strategy":"C","operator_tax_number":"12345678","operator_label":"POS Operator","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":"POS Operator","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},"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":"POS Operator"},"description":"Enable FURS with centralized numbering strategy"},"Update Strategy":{"value":{"numbering_strategy":"B"},"description":"Change to device-level numbering strategy"}}}}},"responses":{"200":{"description":"FURS Settings Updated","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether FURS fiscalization is enabled"},"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","has_certificate"]},"examples":{"Configured Settings":{"value":{"enabled":true,"numbering_strategy":"C","operator_tax_number":"12345678","operator_label":"POS Operator","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":"POS Operator","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/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_number":1},"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"}}}}}}},"/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"}},"required":["business_premise_name","real_estate"],"additionalProperties":false},"examples":{"Physical Store":{"value":{"business_premise_name":"STORE1","numbering_strategy":"C","real_estate":{"property_id":"1234-567-1","cadastral_number":"1234","building_number":"567","building_section":"1","street":"Dunajska cesta","house_number":"22","house_number_additional":"A","community":"Ljubljana"}},"description":"Register a physical store location"},"Office Location":{"value":{"business_premise_name":"OFFICE1","real_estate":{"property_id":"5678-123-2","cadastral_number":"5678","building_number":"123","building_section":"2","street":"Slovenska cesta","house_number":"10","community":"Maribor"}},"description":"Register an office location"}}}}},"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"}},"required":["business_premise_name","movable_premise"],"additionalProperties":false},"examples":{"Food Truck":{"value":{"business_premise_name":"TRUCK1","numbering_strategy":"B","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"}}}}},"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"}},"required":["name"],"additionalProperties":false},"examples":{"POS Terminal":{"value":{"name":"DEVICE1"},"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","electronic_device_name":"POS Terminal 1","business_premise_id":"premise_507f1f77bcf86cd799439011","entity_id":"ent_507f1f77bcf86cd799439011","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"}}}}}}},"/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":"POS Operator","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":"POS Operator","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":"POS Operator","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"}}}}},"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":"POS Operator","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":"POS Operator","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"}},"required":["business_premise_name"],"additionalProperties":false},"examples":{"Physical Store":{"value":{"business_premise_name":"PP1"},"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"}}}}},"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"}}}}}},"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"}},"required":["electronic_device_name"],"additionalProperties":false},"examples":{"POS Terminal":{"value":{"electronic_device_name":"1"},"description":"Register a POS terminal device"}}}}},"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"}}}}}},"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"}}}}}}},"/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"}}}}}}},"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}}}}}},"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"}}}}}}},"/e-invoicing/settings":{"get":{"operationId":"getEInvoicingSettings","summary":"Get e-invoicing settings","description":"Get the current e-invoicing settings 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"},"examples":{"Get E-Invoicing Settings":{"value":{"enabled":true,"provider":"flowin","auto_send":false,"default_scheme_id":"0009"}}}}}},"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":"Update e-invoicing settings for the entity. Only sandbox entities can enable e-invoicing unless live mode is explicitly enabled.","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"},"examples":{"Enable Auto-Send":{"value":{"auto_send":true}}}}}},"responses":{"200":{"description":"Updated settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSettingsResponse"},"examples":{"Updated Settings":{"value":{"enabled":true,"provider":"flowin","auto_send":true,"default_scheme_id":"0009"}}}}}},"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","description":"Register the entity as an e-invoicing supplier with Flowin. This starts the KYC/onboarding process.","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"},"examples":{"Register French Supplier":{"value":{"company_name":"Acme SAS","vat_number":"FR12345678901","company_number":"12345678901234","iban":"FR7630006000011234567890189","address":"123 Rue de la Paix","city":"Paris","post_code":"75001","country_code":"FR","contact_email":"billing@acme.fr","contact_phone":"+33612345678"}}}}}},"responses":{"201":{"description":"Supplier registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSupplier"},"examples":{"Supplier Registered":{"value":{"id":"einv_sup_1234567890","entity_id":"ent_1234567890","environment":"sandbox","flowin_supplier_id":"fl_sup_abc123","provider":"flowin","status":"pending","peppol_registered":false,"company_name":"Acme SAS","vat_number":"FR12345678901","company_number":"12345678901234","country_code":"FR","created_at":"2026-03-01T10:00:00.000Z","updated_at":"2026-03-01T10: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","description":"Get the current e-invoicing supplier onboarding status for this 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":"Supplier status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSupplier"},"examples":{"Active Supplier":{"value":{"id":"einv_sup_1234567890","entity_id":"ent_1234567890","environment":"sandbox","flowin_supplier_id":"fl_sup_abc123","provider":"flowin","status":"active","peppol_registered":true,"company_name":"Acme SAS","vat_number":"FR12345678901","company_number":"12345678901234","country_code":"FR","created_at":"2026-03-01T10:00:00.000Z","updated_at":"2026-03-01T12:00:00.000Z","onboarded_at":"2026-03-01T11: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 data","description":"Update supplier onboarding data (company details). Only allowed before onboarding is complete.","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"},"examples":{"Update Company Name":{"value":{"company_name":"Acme SAS Renamed"}}}}}},"responses":{"200":{"description":"Updated supplier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSupplier"},"examples":{"Updated Supplier":{"value":{"id":"einv_sup_1234567890","entity_id":"ent_1234567890","environment":"sandbox","flowin_supplier_id":"fl_sup_abc123","provider":"flowin","status":"pending","peppol_registered":false,"company_name":"Acme SAS Renamed","vat_number":"FR12345678901","company_number":"12345678901234","country_code":"FR","created_at":"2026-03-01T10:00:00.000Z","updated_at":"2026-03-01T13: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/customer-search":{"post":{"operationId":"searchEInvoicingCustomer","summary":"Search Peppol customer","description":"Check if a recipient is registered on the Peppol network and can receive e-invoices.","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"},"examples":{"Search by SIRET":{"value":{"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"]},"examples":{"Customer Found":{"value":{"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/send/:documentType/:documentId":{"post":{"operationId":"sendEInvoice","summary":"Send e-invoice","description":"Send a document as an e-invoice via the Peppol network. Generates UBL XML and submits to Flowin.","x-codegen-request-body-name":"data","security":[{"Bearer":[]}],"tags":["E-Invoicing"],"parameters":[{"schema":{"type":"string","enum":["invoice","credit_note"],"description":"Type of document to send","example":"invoice"},"required":true,"description":"Type of document to send","name":"documentType","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Document ID","example":"doc_123"},"required":true,"description":"Document ID","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"},"examples":{"Send Invoice":{"value":{"recipient_peppol_id":"0009:98765432109876","recipient_scheme_id":"0009","recipient_name":"Client Corp SARL"}}}}}},"responses":{"201":{"description":"Submission created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EInvoicingSubmission"},"examples":{"Submission Created":{"value":{"id":"einv_sub_1234567890","entity_id":"ent_1234567890","document_id":"inv_1234567890","document_type":"invoice","status":"submitted","recipient_peppol_id":"0009:98765432109876","recipient_name":"Client Corp SARL","submitted_at":"2026-03-01T10:00:00.000Z","created_at":"2026-03-01T10:00:00.000Z","updated_at":"2026-03-01T10: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/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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"]},"examples":{"Submissions List":{"value":{"data":[{"id":"einv_sub_1234567890","entity_id":"ent_1234567890","document_id":"inv_1234567890","document_type":"invoice","status":"delivered","recipient_peppol_id":"0009:98765432109876","recipient_name":"Client Corp SARL","submitted_at":"2026-03-01T10:00:00.000Z","delivered_at":"2026-03-01T10:05:00.000Z","created_at":"2026-03-01T10:00:00.000Z","updated_at":"2026-03-01T10:05:00.000Z"}],"next_cursor":null,"has_more":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"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/e-invoicing/submissions/:id":{"get":{"operationId":"getEInvoicingSubmission","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"},"examples":{"Submission Detail":{"value":{"id":"einv_sub_1234567890","entity_id":"ent_1234567890","document_id":"inv_1234567890","document_type":"invoice","status":"delivered","recipient_peppol_id":"0009:98765432109876","recipient_name":"Client Corp SARL","ubl_xml":"<Invoice>...</Invoice>","submitted_at":"2026-03-01T10:00:00.000Z","delivered_at":"2026-03-01T10:05:00.000Z","created_at":"2026-03-01T10:00:00.000Z","updated_at":"2026-03-01T10:05: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"}}}}}}},"/e-invoicing/submissions/:id/retry":{"post":{"operationId":"retryEInvoicingSubmission","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"},"examples":{"Retried Submission":{"value":{"id":"einv_sub_1234567890","entity_id":"ent_1234567890","document_id":"inv_1234567890","document_type":"invoice","status":"submitted","recipient_peppol_id":"0009:98765432109876","recipient_name":"Client Corp SARL","submitted_at":"2026-03-01T11:00:00.000Z","created_at":"2026-03-01T10:00:00.000Z","updated_at":"2026-03-01T11: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/webhooks/flowin":{"post":{"operationId":"handleFlowinWebhook","summary":"Flowin webhook receiver","description":"Internal endpoint for receiving status updates from Flowin. Not intended for direct API use.","tags":["E-Invoicing"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}},"examples":{"Status Update":{"value":{"event":"submission.status_changed","submission_id":"fl_sub_abc123","status":"delivered","timestamp":"2026-03-01T10:05:00.000Z"}}}}}},"responses":{"200":{"description":"Webhook processed"},"401":{"description":"Invalid webhook signature"}}}},"/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":"Primer 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":"Primer 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":"Primer podjetje 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"}}}}}}},"/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 hosting for Acme","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 cleaning service","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"}}}}},"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 hosting for Acme","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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"]}}]},"required":false,"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 hosting for Acme","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 hosting for Acme","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 hosting for Acme Corp"},"description":"Update recurring invoice name"},"Pause schedule":{"value":{"auto_send":true,"notify_owner":false},"description":"Enable auto-send and disable owner notifications"}}}}},"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 hosting for Acme","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"}}}},"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 hosting for Acme","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"}}}},"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 hosting for Acme","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 hosting for Acme","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 immediately using the source document as template.","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 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 hosting for Acme","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"}}}}}}},"/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"],"description":"Canonical Slovenian legal form for the entity.","example":"sp"},"income_tax_regime":{"type":["string","null"],"enum":["normirani","dejanski"],"description":"Income tax regime used by the Slovenian entity.","example":"normirani"},"vat_profile":{"type":["string","null"],"enum":["standard","special_vat_identified"],"description":"Slovenia-specific VAT subject subtype.","example":"standard"},"tax_residency":{"type":["string","null"],"enum":["resident","non_resident"],"description":"Tax residency status for Slovenian yearly reporting.","example":"resident"},"yearly_reporting":{"type":"object","properties":{"activity_code":{"type":["string","null"],"description":"Primary SKD activity code.","example":"62.010"},"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"],"description":"Accounting / records mode used in the filing.","example":"records"},"normiranec_insurance_basis":{"type":["string","null"],"enum":["full_time_self_employed","other"],"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_code","registration_number","accounting_type","normiranec_insurance_basis","default_withholding_tax_amount","default_foreign_tax_credit_amount"]},"business_form_source":{"type":"string","enum":["stored","registry","unknown"]},"inferred_business_form":{"type":["string","null"],"enum":["sp","doo","dno","club"],"description":"Canonical Slovenian legal form for the entity.","example":"sp"},"supported_exports":{"type":"object","properties":{"yearly_normirani":{"type":"boolean"}},"required":["yearly_normirani"]},"unsupported_reason":{"type":["string","null"]}},"required":["business_form","income_tax_regime","vat_profile","tax_residency","yearly_reporting","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_code":"62.010","registration_number":"1234567","accounting_type":"records","normiranec_insurance_basis":"full_time_self_employed","default_withholding_tax_amount":0,"default_foreign_tax_credit_amount":0},"business_form_source":"stored","inferred_business_form":"sp","supported_exports":{"yearly_normirani":true},"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","enum":["sp","doo","dno","club"],"description":"Canonical Slovenian legal form for the entity.","example":"sp"},"income_tax_regime":{"type":"string","enum":["normirani","dejanski"],"description":"Income tax regime used by the Slovenian entity.","example":"normirani"},"vat_profile":{"type":"string","enum":["standard","special_vat_identified"],"description":"Slovenia-specific VAT subject subtype.","example":"standard"},"tax_residency":{"type":"string","enum":["resident","non_resident"],"description":"Tax residency status for Slovenian yearly reporting.","example":"resident"},"yearly_reporting":{"type":"object","properties":{"activity_code":{"type":["string","null"]},"registration_number":{"type":["string","null"]},"accounting_type":{"type":["string","null"],"enum":["records","single_entry","double_entry"],"description":"Accounting or records mode used for the yearly filing.","example":"records"},"normiranec_insurance_basis":{"type":["string","null"],"enum":["full_time_self_employed","other"],"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}}}}},"example":{"business_form":"sp","income_tax_regime":"normirani","tax_residency":"resident","yearly_reporting":{"activity_code":"62.010","registration_number":"1234567","accounting_type":"records","normiranec_insurance_basis":"full_time_self_employed","default_withholding_tax_amount":0,"default_foreign_tax_credit_amount":0}}}}},"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"],"description":"Canonical Slovenian legal form for the entity.","example":"sp"},"income_tax_regime":{"type":["string","null"],"enum":["normirani","dejanski"],"description":"Income tax regime used by the Slovenian entity.","example":"normirani"},"vat_profile":{"type":["string","null"],"enum":["standard","special_vat_identified"],"description":"Slovenia-specific VAT subject subtype.","example":"standard"},"tax_residency":{"type":["string","null"],"enum":["resident","non_resident"],"description":"Tax residency status for Slovenian yearly reporting.","example":"resident"},"yearly_reporting":{"type":"object","properties":{"activity_code":{"type":["string","null"],"description":"Primary SKD activity code.","example":"62.010"},"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"],"description":"Accounting / records mode used in the filing.","example":"records"},"normiranec_insurance_basis":{"type":["string","null"],"enum":["full_time_self_employed","other"],"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_code","registration_number","accounting_type","normiranec_insurance_basis","default_withholding_tax_amount","default_foreign_tax_credit_amount"]},"business_form_source":{"type":"string","enum":["stored","registry","unknown"]},"inferred_business_form":{"type":["string","null"],"enum":["sp","doo","dno","club"],"description":"Canonical Slovenian legal form for the entity.","example":"sp"},"supported_exports":{"type":"object","properties":{"yearly_normirani":{"type":"boolean"}},"required":["yearly_normirani"]},"unsupported_reason":{"type":["string","null"]}},"required":["business_form","income_tax_regime","vat_profile","tax_residency","yearly_reporting","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_code":"62.010","registration_number":"1234567","accounting_type":"records","normiranec_insurance_basis":"full_time_self_employed","default_withholding_tax_amount":0,"default_foreign_tax_credit_amount":0},"business_form_source":"stored","inferred_business_form":"sp","supported_exports":{"yearly_normirani":true},"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"]},"example":{"year":2025}}}},"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"],"description":"Canonical Slovenian legal form for the entity.","example":"sp"},"income_tax_regime":{"type":["string","null"],"enum":["normirani","dejanski"],"description":"Income tax regime used by the Slovenian entity.","example":"normirani"},"vat_profile":{"type":["string","null"],"enum":["standard","special_vat_identified"],"description":"Slovenia-specific VAT subject subtype.","example":"standard"},"tax_residency":{"type":["string","null"],"enum":["resident","non_resident"],"description":"Tax residency status for Slovenian yearly reporting.","example":"resident"},"yearly_reporting":{"type":"object","properties":{"activity_code":{"type":["string","null"],"description":"Primary SKD activity code.","example":"62.010"},"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"],"description":"Accounting / records mode used in the filing.","example":"records"},"normiranec_insurance_basis":{"type":["string","null"],"enum":["full_time_self_employed","other"],"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_code","registration_number","accounting_type","normiranec_insurance_basis","default_withholding_tax_amount","default_foreign_tax_credit_amount"]},"business_form_source":{"type":"string","enum":["stored","registry","unknown"]},"inferred_business_form":{"type":["string","null"],"enum":["sp","doo","dno","club"],"description":"Canonical Slovenian legal form for the entity.","example":"sp"},"supported_exports":{"type":"object","properties":{"yearly_normirani":{"type":"boolean"}},"required":["yearly_normirani"]},"unsupported_reason":{"type":["string","null"]}},"required":["business_form","income_tax_regime","vat_profile","tax_residency","yearly_reporting","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_code":"62.010","registration_number":"1234567","accounting_type":"records","normiranec_insurance_basis":"full_time_self_employed","default_withholding_tax_amount":0,"default_foreign_tax_credit_amount":0},"business_form_source":"stored","inferred_business_form":"sp","supported_exports":{"yearly_normirani":true},"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"]},"example":{"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}}}}},"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"}}}}}}},"/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","hidden_features":[],"theme":null,"hal_app_id":null,"support_email":null}}}}}}},"/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"],"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}}}}}}},"/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)"}},"required":["shop_domain"],"additionalProperties":false},"examples":{"Basic":{"value":{"shop_domain":"myshop.myshopify.com"},"description":"Start Shopify OAuth flow"},"With options":{"value":{"shop_domain":"myshop.myshopify.com","name":"My Shopify Store","auto_process":true},"description":"Start Shopify OAuth flow with auto-processing 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":{"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"},"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":"My Store"},"description":"Minimal manual integration with only required fields"},"Complete":{"value":{"name":"Shopify Store","source":"shopify","auto_process":true,"metadata":{"store_url":"https://myshop.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":"My Store","source":"manual","is_active":true,"shop_domain":null,"scopes":null,"auto_process":false,"auto_process_on":"paid","default_payment_type":null,"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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"]}}]},"required":false,"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":"My Store","source":"manual","is_active":true,"shop_domain":null,"scopes":null,"auto_process":false,"auto_process_on":"paid","default_payment_type":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 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":"My Store","source":"manual","is_active":true,"shop_domain":null,"scopes":null,"auto_process":false,"auto_process_on":"paid","default_payment_type":null,"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.","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"},"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"},"issue_invoice_for_bank":{"type":"boolean"},"issue_invoice_on_complete":{"type":"boolean"},"auto_process_delay_seconds":{"type":"integer","minimum":0},"auto_reissue_on_update":{"type":"boolean"},"locale":{"type":"string","maxLength":10},"business_premise_id":{"type":"string","maxLength":36},"electronic_device_id":{"type":"string","maxLength":36}},"additionalProperties":false},"examples":{"Update name":{"value":{"name":"Updated Store Name"},"description":"Update integration name"},"Enable auto-processing":{"value":{"auto_process":true,"auto_process_on":"paid"},"description":"Enable automatic invoice creation when orders are paid"}}}}},"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":"My Store","source":"manual","is_active":true,"shop_domain":null,"scopes":null,"auto_process":false,"auto_process_on":"paid","default_payment_type":null,"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"}}}}}},"delete":{"operationId":"deleteOrderIntegration","summary":"Delete an order integration","description":"Soft delete an order integration. If Shopify, webhooks will be unregistered (best effort).","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"}}}},"500":{"description":"Internal Server Error","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":{"$ref":"#/components/schemas/OrderCustomer"},"billing_address":{"$ref":"#/components/schemas/OrderAddress"},"shipping_address":{"$ref":"#/components/schemas/OrderAddress"},"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":"Widget Pro","quantity":2,"price":50,"gross_price":61,"total":100,"total_with_tax":122,"tax_rate":22}]},"description":"Minimal order with required fields"},"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.com","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":"Widget Pro","quantity":2,"price":50,"gross_price":61,"total":100,"total_with_tax":122,"tax_rate":22,"sku":"WP-001"},{"name":"Widget Basic","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":"Widget Pro","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":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response."},"required":false,"description":"Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.","name":"next_cursor","in":"query"},{"schema":{"type":"string","description":"Cursor to fetch the previous page of results. Use the value from pagination.prev_cursor in the previous response."},"required":false,"description":"Cursor to fetch the previous page of results. 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"]}}]},"required":false,"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, 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, 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":"Widget Pro","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":"Widget Pro","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":{"$ref":"#/components/schemas/OrderCustomer"},"billing_address":{"$ref":"#/components/schemas/OrderAddress"},"shipping_address":{"$ref":"#/components/schemas/OrderAddress"},"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"}}}}},"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":"Widget Pro","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"}}}},"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":"Widget Pro","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"}}}}},"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":"Widget Pro","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":"Widget Pro","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"}}}},"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 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"}}}},"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 payment!"}}}}}},"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 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"}}}}}}},"/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"}}}}}},"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"}}}},"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 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"}}}},"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 payment!"}}}}}},"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 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"}}}}}}},"/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"}}}},"responses":{"200":{"description":"Organization list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyAuthResponse"}}}},"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":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMigrationJobRequest"}}}},"responses":{"202":{"description":"Migration job created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMigrationJobResponse"}}}},"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"}}}}}}},"/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"}}}},"404":{"description":"Job not found"}}}}},"webhooks":{}}