{
  "components": {
    "responses": {
      "PdfResponse": {
        "content": {
          "application/pdf": {
            "schema": {
              "description": "Binary PDF bytes",
              "format": "binary",
              "type": "string"
            }
          }
        },
        "description": "Binary PDF response"
      }
    },
    "schemas": {
      "AccessibleCompany": {
        "description": "A company the signed-in user may switch into.",
        "properties": {
          "fiscalId": {
            "description": "Company tax identifier (NIF/VAT/etc.).",
            "type": "string"
          },
          "id": {
            "description": "Opaque company identifier.",
            "type": "string"
          },
          "isSettled": {
            "description": "Whether the company has completed registration (settlement).",
            "type": "boolean"
          },
          "name": {
            "description": "Company display name.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "fiscalId",
          "isSettled"
        ],
        "type": "object"
      },
      "AddCompanyUserRequest": {
        "properties": {
          "email": {
            "description": "Email of the user to admit to the active company.",
            "type": "string"
          },
          "expiresAt": {
            "description": "RFC 3339 timestamp when access should end; absent means never.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "kind": {
            "$ref": "#/components/schemas/CompanyUserKind",
            "description": "Which credential they sign in with. `password` creates the account and\nmails it a generated password; `oauth` writes the membership and waits\nfor their first sign-in. `invited` is not accepted: it is what an\n`oauth` member looks like before that sign-in."
          },
          "language": {
            "description": "Language tag (e.g. `en_US`, `es_ES`) the account's emails are written\nin; defaults to the acting user's.",
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "description": "Display name for a newly created password account; defaults to the\naddress's local part.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "email",
          "kind"
        ],
        "type": "object"
      },
      "Address": {
        "description": "A legally-complete postal address for the company that issues invoices (our\nown company).",
        "properties": {
          "city": {
            "description": "City or town.",
            "type": "string"
          },
          "country": {
            "description": "Country.",
            "type": "string"
          },
          "lines": {
            "description": "Street address lines.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "state": {
            "description": "State, province, or region.",
            "type": [
              "string",
              "null"
            ]
          },
          "zipcode": {
            "description": "Postal / ZIP code.",
            "type": "string"
          }
        },
        "required": [
          "lines",
          "zipcode",
          "city",
          "country"
        ],
        "type": "object"
      },
      "AiAuditEntry": {
        "description": "A captured AI action awaiting (or having received) human review.",
        "properties": {
          "action": {
            "description": "Human-readable logical action, e.g. `invoice.create`.",
            "type": "string"
          },
          "createdAt": {
            "description": "RFC 3339 timestamp when the action was captured.",
            "format": "date-time",
            "type": "string"
          },
          "errorMessage": {
            "description": "Error text if an approved action failed to replay.",
            "type": [
              "string",
              "null"
            ]
          },
          "httpMethod": {
            "description": "HTTP method of the intercepted request.",
            "type": "string"
          },
          "httpPath": {
            "description": "HTTP path of the intercepted request.",
            "type": "string"
          },
          "id": {
            "description": "Opaque audit entry identifier.",
            "type": "string"
          },
          "requestBody": {
            "description": "The captured request payload (JSON), so a reviewer can see what will run.",
            "type": [
              "string",
              "null"
            ]
          },
          "resourceId": {
            "description": "Id of the resource created/affected once approved and replayed.",
            "type": [
              "string",
              "null"
            ]
          },
          "reviewedAt": {
            "description": "RFC 3339 timestamp when the entry was approved or rejected.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "reviewedBy": {
            "description": "Id of the human who approved or rejected the entry.",
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "description": "Transport the request arrived through: `api` or `mcp`.",
            "type": "string"
          },
          "status": {
            "description": "`pending`, `approved`, `rejected`, or `failed`.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "source",
          "action",
          "httpMethod",
          "httpPath",
          "status",
          "createdAt"
        ],
        "type": "object"
      },
      "BalanceSnapshotView": {
        "description": "A stated balance for an account at a point in time.",
        "properties": {
          "as_of_date": {
            "description": "Date the balance was observed (RFC 3339).",
            "format": "date-time",
            "type": "string"
          },
          "balance_minor": {
            "description": "The stated balance in the account's currency (minor units, signed).",
            "format": "int64",
            "type": "integer"
          },
          "bank_account_id": {
            "description": "The account this snapshot belongs to.",
            "type": "string"
          },
          "created_at": {
            "description": "Creation timestamp (RFC 3339).",
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Opaque snapshot identifier.",
            "type": "string"
          },
          "note": {
            "description": "Optional user note.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "bank_account_id",
          "as_of_date",
          "balance_minor",
          "created_at"
        ],
        "type": "object"
      },
      "BankAccountDetail": {
        "description": "A bank account with its full balance-snapshot history.",
        "properties": {
          "account": {
            "$ref": "#/components/schemas/BankAccountView",
            "description": "The account (with its current balance)."
          },
          "snapshots": {
            "description": "Balance snapshots, newest first (the first entry is the current balance,\nthe last is the opening balance).",
            "items": {
              "$ref": "#/components/schemas/BalanceSnapshotView"
            },
            "type": "array"
          }
        },
        "required": [
          "account",
          "snapshots"
        ],
        "type": "object"
      },
      "BankAccountView": {
        "description": "A company bank account with its current balance (from the latest snapshot).",
        "properties": {
          "balance_as_of": {
            "description": "Date of the most recent balance snapshot (RFC 3339), if any.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "bank_name": {
            "description": "Institution name.",
            "type": [
              "string",
              "null"
            ]
          },
          "bic": {
            "description": "Bank Identifier Code / SWIFT.",
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "description": "Creation timestamp (RFC 3339).",
            "format": "date-time",
            "type": "string"
          },
          "currency_code": {
            "description": "ISO 4217 currency code of the account.",
            "type": "string"
          },
          "current_balance_minor": {
            "description": "Current balance in the account's currency (minor units, signed), taken\nfrom the most recent balance snapshot. `null` until a balance is recorded.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "iban": {
            "description": "International Bank Account Number.",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Opaque account identifier.",
            "type": "string"
          },
          "is_main": {
            "description": "Whether this is the company's default account (pre-selected wherever an\naccount is picked). At most one account per company is the default.",
            "type": "boolean"
          },
          "name": {
            "description": "User-facing label, e.g. \"BBVA current account\".",
            "type": "string"
          },
          "updated_at": {
            "description": "Last-update timestamp (RFC 3339).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "currency_code",
          "is_main",
          "created_at"
        ],
        "type": "object"
      },
      "BulkActionResult": {
        "description": "Result of a bulk action.",
        "properties": {
          "affected": {
            "description": "How many of the requested documents the action actually applied to.",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "affected"
        ],
        "type": "object"
      },
      "BulkIdsRequest": {
        "description": "Payload naming the documents a bulk action applies to. Ids that don't\nresolve for the caller's company are ignored.",
        "properties": {
          "ids": {
            "description": "Document ids the action applies to.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "ids"
        ],
        "type": "object"
      },
      "Company": {
        "description": "A company as returned after completing registration.",
        "properties": {
          "email": {
            "description": "Primary contact email.",
            "type": "string"
          },
          "fiscal_id": {
            "description": "Company tax identifier (NIF/VAT/etc.).",
            "type": "string"
          },
          "id": {
            "description": "Opaque company identifier.",
            "type": "string"
          },
          "is_settled": {
            "description": "Whether the company has completed registration (settlement).",
            "type": "boolean"
          },
          "name": {
            "description": "Company display name.",
            "type": "string"
          },
          "phone": {
            "description": "Primary contact phone.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "fiscal_id",
          "email",
          "phone",
          "is_settled"
        ],
        "type": "object"
      },
      "CompanyConfiguration": {
        "description": "Full editable configuration of a company.",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/Address",
            "description": "Company postal address."
          },
          "correctiveInvoiceReferenceFormat": {
            "description": "Format for the frozen reference of corrective invoices; uses `{year}`\nand `{number}` placeholders (e.g. `R-INV-{year}-{number}`).",
            "type": "string"
          },
          "createdAt": {
            "description": "RFC 3339 creation timestamp.",
            "format": "date-time",
            "type": "string"
          },
          "currencyCode": {
            "description": "ISO 4217 default currency for the company.",
            "type": [
              "string",
              "null"
            ]
          },
          "customPlaceholders": {
            "description": "Custom placeholder definitions available to the templates.",
            "items": {
              "$ref": "#/components/schemas/CustomPlaceholder"
            },
            "type": "array"
          },
          "email": {
            "description": "Primary contact email.",
            "type": "string"
          },
          "firstCorrectiveInvoiceYearlyNumber": {
            "description": "Starting sequence number for the first corrective invoice of each year.",
            "format": "int64",
            "type": "integer"
          },
          "firstInvoiceYearlyNumber": {
            "description": "Starting sequence number for the first invoice of each year.",
            "format": "int64",
            "type": "integer"
          },
          "fiscalId": {
            "description": "Company tax identifier (NIF/VAT/etc.).",
            "type": "string"
          },
          "footerInvoiceTypst": {
            "description": "Typst snippet rendered in the invoice footer.",
            "type": [
              "string",
              "null"
            ]
          },
          "friendlyName": {
            "description": "Short informal name shown in the UI.",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Opaque company identifier.",
            "type": "string"
          },
          "invoiceReferenceFormat": {
            "description": "Format for the frozen reference of regular invoices; uses `{year}` and\n`{number}` placeholders (e.g. `INV-{year}-{number}`).",
            "type": "string"
          },
          "isSettled": {
            "description": "Whether the company has completed registration (settlement).",
            "type": "boolean"
          },
          "name": {
            "description": "Company legal name.",
            "type": "string"
          },
          "phone": {
            "description": "Primary contact phone.",
            "type": "string"
          },
          "postInvoiceTypst": {
            "description": "Typst snippet appended after the invoice body.",
            "type": [
              "string",
              "null"
            ]
          },
          "proformaReferenceFormat": {
            "description": "Format for the frozen reference of proformas; uses `{year}` and\n`{number}` placeholders (e.g. `PRO-{year}-{number}`).",
            "type": "string"
          },
          "type": {
            "description": "Company kind (country-prefixed).",
            "type": [
              "string",
              "null"
            ]
          },
          "updatedAt": {
            "description": "RFC 3339 timestamp of the last update.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "viesVatId": {
            "description": "VIES-registered intra-EU VAT identifier.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "fiscalId",
          "email",
          "phone",
          "address",
          "customPlaceholders",
          "firstInvoiceYearlyNumber",
          "firstCorrectiveInvoiceYearlyNumber",
          "invoiceReferenceFormat",
          "correctiveInvoiceReferenceFormat",
          "proformaReferenceFormat",
          "isSettled",
          "createdAt"
        ],
        "type": "object"
      },
      "CompanyInfo": {
        "description": "The active company attached to the current session.",
        "properties": {
          "address": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Address",
                "description": "Absent until the company has completed registration; once present it is\na legally-complete [`Address`]."
              }
            ]
          },
          "email": {
            "description": "Primary contact email.",
            "type": [
              "string",
              "null"
            ]
          },
          "fiscalId": {
            "description": "Company tax identifier (NIF/VAT/etc.).",
            "type": "string"
          },
          "id": {
            "description": "Opaque company identifier.",
            "type": "string"
          },
          "isSettled": {
            "description": "Whether the company has completed registration (settlement).",
            "type": "boolean"
          },
          "name": {
            "description": "Company display name.",
            "type": "string"
          },
          "phone": {
            "description": "Primary contact phone.",
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "description": "Company kind (country-prefixed).",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "fiscalId",
          "isSettled"
        ],
        "type": "object"
      },
      "CompanyUser": {
        "description": "One person's access to the company.",
        "properties": {
          "email": {
            "description": "Email of the member, and the identifier every action here takes.",
            "type": "string"
          },
          "expiresAt": {
            "description": "RFC 3339 timestamp when access ends by itself; absent means never.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "kind": {
            "$ref": "#/components/schemas/CompanyUserKind"
          },
          "memberSince": {
            "description": "RFC 3339 timestamp of when the address was first admitted. Survives a\ndeactivation, so it states since when this person has had access to the\ncompany's data.",
            "format": "date-time",
            "type": "string"
          },
          "name": {
            "description": "Display name of the account; absent until one exists.",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/CompanyUserStatus"
          }
        },
        "required": [
          "email",
          "kind",
          "status",
          "memberSince"
        ],
        "type": "object"
      },
      "CompanyUserKind": {
        "description": "How a member proves who they are.",
        "enum": [
          "oauth",
          "password",
          "invited"
        ],
        "type": "string"
      },
      "CompanyUserStatus": {
        "description": "Whether a membership grants access, and if not, why not.",
        "enum": [
          "active",
          "deactivated",
          "expired"
        ],
        "type": "string"
      },
      "CompleteCompanyRegistrationRequest": {
        "properties": {
          "address": {
            "$ref": "#/components/schemas/Address",
            "description": "Legally-complete postal address."
          },
          "email": {
            "description": "Primary contact email.",
            "type": "string"
          },
          "fiscal_id": {
            "description": "Company tax identifier (NIF/VAT/etc.).",
            "type": "string"
          },
          "name": {
            "description": "Company display name.",
            "type": "string"
          },
          "phone": {
            "description": "Primary contact phone.",
            "type": "string"
          },
          "type": {
            "description": "Company kind (country-prefixed).",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "name",
          "fiscal_id",
          "email",
          "phone",
          "address"
        ],
        "type": "object"
      },
      "CorrectionReason": {
        "description": "The reason for a corrective invoice (maps to Verifactu `TipoFactura` R1-R5).",
        "enum": [
          "R1",
          "R2",
          "R3",
          "R4",
          "R5"
        ],
        "type": "string"
      },
      "CorrectiveInvoice": {
        "description": "A corrective invoice: an invoice that corrects a previously issued one.\n\nReturned only by the correction endpoints (`POST /v1/invoices/{id}/correct`\nand `POST /v1/invoices/{id}/corrections`), so `corrected_invoice_id` is\nalways present and the VeriFactu corrective metadata is meaningful here.",
        "properties": {
          "corrected_invoice_id": {
            "description": "The invoice this one corrects.",
            "type": "string"
          },
          "currency_code": {
            "description": "ISO 4217 currency the invoice amounts are expressed in.",
            "type": "string"
          },
          "custom_placeholder_values": {
            "description": "Per-recipient template placeholder values captured on this invoice.",
            "items": {
              "$ref": "#/components/schemas/CustomPlaceholderValue"
            },
            "type": "array"
          },
          "id": {
            "description": "Opaque invoice identifier.",
            "type": "string"
          },
          "invoice_number": {
            "description": "Fiscal invoice number assigned at issue. Null while a draft.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "invoice_year": {
            "description": "Fiscal year of the invoice number, assigned at issue. Null while a draft.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "issued_at": {
            "description": "When the invoice was issued (finalized). Null while a draft.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "lines": {
            "description": "The invoice line items.",
            "items": {
              "$ref": "#/components/schemas/InvoiceLine"
            },
            "type": "array"
          },
          "order_number": {
            "description": "Draft ordering sequence number. Null once issued.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "order_year": {
            "description": "Year the draft ordering sequence belongs to. Null once issued.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "origin": {
            "$ref": "#/components/schemas/InvoiceOrigin",
            "description": "How the invoice came to exist here."
          },
          "recipient_id": {
            "description": "Recipient entity the invoice is billed to.",
            "type": "string"
          },
          "reference": {
            "description": "The frozen document reference, once issued. Null while a draft.",
            "type": [
              "string",
              "null"
            ]
          },
          "supply_type": {
            "$ref": "#/components/schemas/SupplyType",
            "description": "Whether the lines are goods or services."
          },
          "total": {
            "description": "Total in cents (sum of all lines).",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "verifactu": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/InvoiceVerifactu",
                "description": "VeriFactu-specific corrective metadata; present only for Spanish (`ES-…`)\nissuers."
              }
            ]
          }
        },
        "required": [
          "id",
          "recipient_id",
          "origin",
          "supply_type",
          "corrected_invoice_id",
          "lines",
          "custom_placeholder_values",
          "currency_code"
        ],
        "type": "object"
      },
      "CreateBalanceSnapshotRequest": {
        "description": "Payload to record a balance snapshot.",
        "properties": {
          "as_of_date": {
            "description": "Date the balance was observed (RFC 3339). Defaults to now when omitted.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "balance_minor": {
            "description": "The balance in the account's currency (minor units, signed).",
            "format": "int64",
            "type": "integer"
          },
          "note": {
            "description": "Optional note (e.g. \"opening balance\").",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "balance_minor"
        ],
        "type": "object"
      },
      "CreateBankAccountRequest": {
        "description": "Payload to create a bank account.",
        "properties": {
          "bank_name": {
            "description": "Institution name.",
            "type": [
              "string",
              "null"
            ]
          },
          "bic": {
            "description": "Bank Identifier Code / SWIFT.",
            "type": [
              "string",
              "null"
            ]
          },
          "currency_code": {
            "description": "ISO 4217 currency code. Defaults to EUR when omitted.",
            "type": [
              "string",
              "null"
            ]
          },
          "iban": {
            "description": "International Bank Account Number.",
            "type": [
              "string",
              "null"
            ]
          },
          "is_main": {
            "description": "Make this the company's default account. The first account is always made\nthe default regardless of this flag.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "name": {
            "description": "User-facing label for the account.",
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "CreateCorrectiveInvoiceRequest": {
        "properties": {
          "custom_placeholder_values": {
            "description": "Override the custom placeholder values. When empty, the corrected\ninvoice's are kept.",
            "items": {
              "$ref": "#/components/schemas/CustomPlaceholderValue"
            },
            "type": "array"
          },
          "exchange_rates": {
            "description": "Override the frozen exchange rates. When empty, the corrected invoice's\nare kept.",
            "items": {
              "$ref": "#/components/schemas/ExchangeRateEntry"
            },
            "type": "array"
          },
          "lines": {
            "description": "The corrective lines. Leave empty to copy the corrected invoice's lines\nwith negated amounts (a full reversal).",
            "items": {
              "$ref": "#/components/schemas/InvoiceLineRequest"
            },
            "type": "array"
          },
          "supply_type": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SupplyType",
                "description": "Override the supply type. When omitted, the corrected invoice's is kept."
              }
            ]
          },
          "verifactu": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/InvoiceVerifactu",
                "description": "VeriFactu-specific corrective metadata (the legal reason). Only meaningful\nfor Spanish (`ES-…`) issuers, for whom it defaults to `R1` when omitted;\nignored for issuers in other countries."
              }
            ]
          }
        },
        "type": "object"
      },
      "CreateEntityRequest": {
        "description": "Payload to create a new entity.",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/ThirdPartyAddress",
            "description": "Postal address; its country is mandatory."
          },
          "currency_code": {
            "description": "ISO 4217 currency code; defaults to the company currency when omitted.",
            "type": [
              "string",
              "null"
            ]
          },
          "fiscal_id": {
            "description": "Tax identifier (NIF/VAT number/etc.).",
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "description": "Display name of the entity.",
            "type": "string"
          },
          "template": {
            "$ref": "#/components/schemas/EntityTemplate",
            "description": "Per-recipient Typst template overrides and custom placeholders."
          },
          "type": {
            "description": "Country the entity is incorporated in, followed by `-` and its legal\nform: `ES:SL`, `DE:GmbH`, `US:Inc`. The country prefix is what decides\nhow documents to and from this entity are taxed and declared, so it is\nmandatory and is not derived from the postal address.",
            "type": "string"
          },
          "verifactu": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EntityVerifactu",
                "description": "VeriFactu-specific settings for this entity."
              }
            ]
          },
          "vies_vat_id": {
            "description": "VIES-registered intra-EU VAT number.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "name",
          "type",
          "address"
        ],
        "type": "object"
      },
      "CreateExpenseRequest": {
        "description": "Payload to create a new expense (a bill received from a supplier).",
        "properties": {
          "category": {
            "description": "Free-form accounting category for the expense.",
            "type": [
              "string",
              "null"
            ]
          },
          "currency_code": {
            "description": "ISO 4217 currency code of the expense.",
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "description": "Free-form description of the expense.",
            "type": [
              "string",
              "null"
            ]
          },
          "exchange_rate": {
            "description": "Frozen FX rate used to convert the expense to the company currency.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "expense_date": {
            "description": "Date of the expense (RFC 3339).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "invoice_reference": {
            "description": "The supplier invoice's reference/number (required, non-empty, unique per\ncompany+supplier).",
            "type": "string"
          },
          "lines": {
            "description": "Line items making up the expense.",
            "items": {
              "$ref": "#/components/schemas/ExpenseLineRequest"
            },
            "type": "array"
          },
          "supplier_id": {
            "description": "Supplier entity id (the counterparty the bill was received from).",
            "type": "string"
          }
        },
        "required": [
          "supplier_id",
          "invoice_reference",
          "lines"
        ],
        "type": "object"
      },
      "CreateInvoiceRequest": {
        "properties": {
          "bank_account_ids": {
            "description": "Ids of the company's bank accounts to show on the invoice as payment\ninstructions. Each is snapshotted onto the invoice at creation; unknown\nids are ignored.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "currency_code": {
            "description": "ISO 4217 currency the invoice amounts are expressed in. When omitted (or\nempty) it falls back to the recipient entity's configured currency.",
            "type": [
              "string",
              "null"
            ]
          },
          "custom_placeholder_values": {
            "description": "Per-recipient template placeholder values for this invoice.",
            "items": {
              "$ref": "#/components/schemas/CustomPlaceholderValue"
            },
            "type": "array"
          },
          "exchange_rates": {
            "description": "Manually-supplied exchange rates for the currency pairs the effective\ntemplate uses. A pair supplied here is frozen as-is and is not fetched\nfrom the provider at issue time.",
            "items": {
              "$ref": "#/components/schemas/ExchangeRateEntry"
            },
            "type": "array"
          },
          "lines": {
            "description": "The invoice line items.",
            "items": {
              "$ref": "#/components/schemas/InvoiceLineRequest"
            },
            "type": "array"
          },
          "recipient_id": {
            "description": "Recipient entity the invoice is billed to.",
            "type": "string"
          },
          "supply_type": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SupplyType",
                "description": "Whether the lines are goods or services. Defaults to services."
              }
            ]
          }
        },
        "required": [
          "recipient_id",
          "lines"
        ],
        "type": "object"
      },
      "CurrencyAmount": {
        "properties": {
          "amount_minor": {
            "description": "Amount in cents of `currency`.",
            "format": "int64",
            "type": "integer"
          },
          "currency": {
            "description": "ISO 4217 currency code.",
            "type": "string"
          }
        },
        "required": [
          "currency",
          "amount_minor"
        ],
        "type": "object"
      },
      "CurrentSession": {
        "description": "The current session: the signed-in user, their active company, and consent\nstate.",
        "properties": {
          "accessibleCompanies": {
            "description": "Other companies this user can switch into.",
            "items": {
              "$ref": "#/components/schemas/AccessibleCompany"
            },
            "type": "array"
          },
          "company": {
            "$ref": "#/components/schemas/CompanyInfo",
            "description": "The company currently active for this session."
          },
          "currentDpaId": {
            "description": "Identifier of the currently-published data processing agreement, if any.",
            "type": [
              "string",
              "null"
            ]
          },
          "currentPrivacyPolicyId": {
            "description": "Identifier of the currently-published privacy policy, if any.",
            "type": [
              "string",
              "null"
            ]
          },
          "currentTosId": {
            "description": "Identifier of the currently-published terms of service, if any.",
            "type": [
              "string",
              "null"
            ]
          },
          "dpaAgreed": {
            "description": "Whether the user has agreed to the current data processing agreement.",
            "type": "boolean"
          },
          "email": {
            "description": "User email address.",
            "type": "string"
          },
          "id": {
            "description": "Opaque user identifier.",
            "type": "string"
          },
          "language": {
            "description": "User's preferred UI language.",
            "type": "string"
          },
          "name": {
            "description": "User display name.",
            "type": "string"
          },
          "privacyPolicyAgreed": {
            "description": "Whether the user has agreed to the current privacy policy.",
            "type": "boolean"
          },
          "profileImageUrl": {
            "description": "URL of the user's profile image.",
            "type": "string"
          },
          "tosAgreed": {
            "description": "Whether the user has agreed to the current terms of service.",
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "name",
          "profileImageUrl",
          "email",
          "language",
          "company",
          "accessibleCompanies",
          "tosAgreed",
          "privacyPolicyAgreed",
          "dpaAgreed"
        ],
        "type": "object"
      },
      "CustomPlaceholder": {
        "description": "Per-company definition of a custom invoice template placeholder.\n\nCompanies declare these in their configuration; each one becomes a\n`{{key}}` token usable in the post/footer invoice Typst templates and an\ninput field shown on the invoice creation form. Definitions are *not*\nsnapshotted: only the per-invoice [`CustomPlaceholderValue`]s are.",
        "properties": {
          "default": {
            "description": "Optional default value applied when none is provided at creation time.",
            "type": [
              "string",
              "null"
            ]
          },
          "key": {
            "description": "Placeholder key, used as `{{key}}` in the template.",
            "type": "string"
          },
          "label": {
            "description": "Human-friendly label shown in the GUI form.",
            "type": "string"
          },
          "required": {
            "description": "Whether a value must be provided when creating an invoice.",
            "type": "boolean"
          }
        },
        "required": [
          "key",
          "label"
        ],
        "type": "object"
      },
      "CustomPlaceholderValue": {
        "description": "Per-invoice value for a custom placeholder, captured at creation time and\nfrozen on issue (snapshot pattern). These are substituted into the\nsnapshotted template when the PDF is rendered.",
        "properties": {
          "key": {
            "description": "Placeholder key this value is for, matching a [`CustomPlaceholder`] key.",
            "type": "string"
          },
          "value": {
            "description": "The value substituted for `{{key}}` when rendering the template.",
            "type": "string"
          }
        },
        "required": [
          "key",
          "value"
        ],
        "type": "object"
      },
      "CustomerStats": {
        "properties": {
          "new_this_month": {
            "description": "Customers whose first issued invoice falls in the current calendar month.",
            "format": "int64",
            "type": "integer"
          },
          "total": {
            "description": "Distinct entities the company has issued an invoice to, all time.\nSuppliers and other entities on file are not customers.",
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "total",
          "new_this_month"
        ],
        "type": "object"
      },
      "Dashboard": {
        "description": "Aggregated, company-scoped statistics rendered on the home dashboard.\n\nEvery monetary figure is an integer amount in the currency's minor units\n(e.g. cents). Because the app tracks no FX-normalised ledger, amounts are\n**never summed across currencies**: totals are grouped by `currency`, and\nthe single-series views (`monthly_revenue`, `top_customers`) are scoped to\n`primary_currency` (the company's default). The `*_this_month` figures cover\nthe current calendar month (UTC).",
        "properties": {
          "customer_stats": {
            "$ref": "#/components/schemas/CustomerStats",
            "description": "Customer counts (total and new this month)."
          },
          "expenses_this_month": {
            "description": "Recorded expenses this month, grouped by currency.",
            "items": {
              "$ref": "#/components/schemas/CurrencyAmount"
            },
            "type": "array"
          },
          "expenses_total": {
            "description": "Recorded expenses, all time, grouped by currency.",
            "items": {
              "$ref": "#/components/schemas/CurrencyAmount"
            },
            "type": "array"
          },
          "invoice_counts": {
            "$ref": "#/components/schemas/InvoiceCounts",
            "description": "Invoice counts broken down by status."
          },
          "monthly_revenue": {
            "description": "Issued-invoice revenue per month for the trailing 12 months (oldest\nfirst), in `primary_currency`.",
            "items": {
              "$ref": "#/components/schemas/MonthlyRevenue"
            },
            "type": "array"
          },
          "points_balance_minor": {
            "description": "Prepaid points (deposit) balance, in minor units. Its unit is points, not\na currency: display it as points.",
            "format": "int64",
            "type": "integer"
          },
          "points_currency": {
            "description": "ISO 4217 currency the deposit was bought with (points are credited one\nfor one). This is what a top-up is charged in, and never the unit of\n`points_balance_minor`.",
            "type": "string"
          },
          "primary_currency": {
            "description": "The company's default currency; the reporting currency for the\nsingle-series views.",
            "type": "string"
          },
          "revenue_this_month": {
            "description": "Net billed amount of issued invoices this month, grouped by currency.",
            "items": {
              "$ref": "#/components/schemas/CurrencyAmount"
            },
            "type": "array"
          },
          "revenue_total": {
            "description": "Net billed amount of issued invoices, all time, grouped by currency.",
            "items": {
              "$ref": "#/components/schemas/CurrencyAmount"
            },
            "type": "array"
          },
          "subscription_tier": {
            "description": "Current subscription tier (e.g. `on-demand`, `pro`), if any.",
            "type": [
              "string",
              "null"
            ]
          },
          "top_customers": {
            "description": "Customers ranked by issued revenue in `primary_currency` (top 5).",
            "items": {
              "$ref": "#/components/schemas/TopCustomer"
            },
            "type": "array"
          }
        },
        "required": [
          "primary_currency",
          "invoice_counts",
          "customer_stats",
          "revenue_total",
          "revenue_this_month",
          "expenses_total",
          "expenses_this_month",
          "points_balance_minor",
          "points_currency",
          "monthly_revenue",
          "top_customers"
        ],
        "type": "object"
      },
      "Entity": {
        "description": "A client or supplier you invoice or are invoiced by.",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/ThirdPartyAddress",
            "description": "Postal address; its country is always present."
          },
          "created_at": {
            "description": "Creation timestamp (RFC 3339).",
            "format": "date-time",
            "type": "string"
          },
          "currency_code": {
            "description": "ISO 4217 currency code used by default for this entity's documents.",
            "type": "string"
          },
          "fiscal_id": {
            "description": "Tax identifier (NIF/VAT number/etc.).",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Opaque entity identifier.",
            "type": "string"
          },
          "metadata": {
            "description": "Free-form metadata attached to the entity.",
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "description": "Display name of the entity.",
            "type": "string"
          },
          "template": {
            "$ref": "#/components/schemas/EntityTemplate",
            "description": "Per-recipient Typst template overrides and custom placeholders."
          },
          "type": {
            "description": "Entity type/country-prefixed kind (drives legal placement).",
            "type": "string"
          },
          "updated_at": {
            "description": "Last-update timestamp (RFC 3339).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "verifactu": {
            "$ref": "#/components/schemas/EntityVerifactu",
            "description": "VeriFactu-specific settings for this entity."
          },
          "vies_vat_id": {
            "description": "VIES-registered intra-EU VAT number.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "type",
          "address",
          "currency_code",
          "verifactu",
          "template",
          "created_at"
        ],
        "type": "object"
      },
      "EntityTemplate": {
        "description": "Per-recipient invoice template override. Empty snippets mean the entity\ninherits the company's template; `custom_placeholders` extend the company's.",
        "properties": {
          "custom_placeholders": {
            "description": "Additional custom placeholders that extend the company's set.",
            "items": {
              "$ref": "#/components/schemas/CustomPlaceholder"
            },
            "type": "array"
          },
          "footer_invoice_typst": {
            "description": "Typst snippet rendered in the invoice footer; empty inherits the\ncompany template.",
            "type": [
              "string",
              "null"
            ]
          },
          "post_invoice_typst": {
            "description": "Typst snippet rendered after the invoice body; empty inherits the\ncompany template.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "EntityVerifactu": {
        "description": "VeriFactu-specific settings for an entity. Kept in a dedicated nested object\nso VeriFactu concerns never pollute the top-level entity fields.",
        "properties": {
          "under_recargo_equivalencia": {
            "description": "Recipient operates under the Spanish \"recargo de equivalencia\" regime.",
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "ExchangeRateEntry": {
        "description": "A caller-supplied exchange rate for a currency pair. `rate` is a decimal\nstring (e.g. \"1.0842\").",
        "properties": {
          "from": {
            "description": "Base currency (ISO 4217) the rate converts from.",
            "type": "string"
          },
          "rate": {
            "description": "The conversion rate as a decimal string (e.g. \"1.0842\").",
            "type": "string"
          },
          "to": {
            "description": "Quote currency (ISO 4217) the rate converts to.",
            "type": "string"
          }
        },
        "required": [
          "from",
          "to",
          "rate"
        ],
        "type": "object"
      },
      "ExchangeRatePair": {
        "description": "A currency pair (base→quote) the effective template requires a rate for.",
        "properties": {
          "from": {
            "description": "Base currency (ISO 4217) the template converts from.",
            "type": "string"
          },
          "to": {
            "description": "Quote currency (ISO 4217) the template converts to.",
            "type": "string"
          }
        },
        "required": [
          "from",
          "to"
        ],
        "type": "object"
      },
      "Expense": {
        "description": "A full expense with its line items and optional receipt.",
        "properties": {
          "category": {
            "description": "Free-form accounting category for the expense.",
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "description": "Creation timestamp (RFC 3339).",
            "format": "date-time",
            "type": "string"
          },
          "currency_code": {
            "description": "ISO 4217 currency code of the expense.",
            "type": "string"
          },
          "description": {
            "description": "Free-form description of the expense.",
            "type": [
              "string",
              "null"
            ]
          },
          "exchange_rate": {
            "description": "Frozen FX rate used to convert the expense to the company currency.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "expense_date": {
            "description": "Date of the expense (RFC 3339).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Opaque expense identifier.",
            "type": "string"
          },
          "invoice_reference": {
            "description": "The supplier invoice's own reference/number.",
            "type": "string"
          },
          "lines": {
            "description": "Line items making up the expense.",
            "items": {
              "$ref": "#/components/schemas/ExpenseLine"
            },
            "type": "array"
          },
          "receipt": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Receipt",
                "description": "Attached receipt metadata, if any."
              }
            ]
          },
          "supplier_fiscal_id": {
            "description": "Supplier tax identifier (NIF/VAT number/etc.).",
            "type": [
              "string",
              "null"
            ]
          },
          "supplier_id": {
            "description": "Supplier entity id (the counterparty the bill was received from).",
            "type": "string"
          },
          "supplier_name": {
            "description": "Supplier display name.",
            "type": [
              "string",
              "null"
            ]
          },
          "total": {
            "description": "Total amount in cents, computed from the lines.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "updated_at": {
            "description": "Last-update timestamp (RFC 3339).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "supplier_id",
          "invoice_reference",
          "currency_code",
          "lines",
          "created_at"
        ],
        "type": "object"
      },
      "ExpenseLine": {
        "description": "A single line item of an expense.",
        "properties": {
          "concept": {
            "description": "Line description.",
            "type": [
              "string",
              "null"
            ]
          },
          "date_end": {
            "description": "End of the period this line covers (RFC 3339).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "date_start": {
            "description": "Start of the period this line covers (RFC 3339).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "deductible": {
            "description": "Whether that tax is reclaimable. Omitted defers to the tax type default.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "expense_id": {
            "description": "Identifier of the expense this line belongs to.",
            "type": "string"
          },
          "id": {
            "description": "Opaque line identifier.",
            "type": "string"
          },
          "quantity": {
            "description": "Quantity of units for this line, as a decimal number of units.",
            "format": "double",
            "type": [
              "number",
              "null"
            ]
          },
          "quantity_unit": {
            "description": "Label for the quantity unit.",
            "type": [
              "string",
              "null"
            ]
          },
          "subtotal": {
            "description": "Line subtotal in cents.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "tax_amount": {
            "description": "Tax amount for this line in cents.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "tax_type": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/TaxType",
                "description": "Whether the line is cost base (`item`) or tax borne on the purchase,\nreclaimable (`deductible_tax`) or not (`non_deductible_tax`). A\nnon-deductible tax counts towards net expenses, not towards input tax.\nDefaults to `item`."
              }
            ]
          },
          "unit_price": {
            "description": "Unit price in cents.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "unit_unit": {
            "description": "Label for the unit price unit.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "expense_id"
        ],
        "type": "object"
      },
      "ExpenseLineRequest": {
        "description": "A single line item to add to a new expense.",
        "properties": {
          "concept": {
            "description": "Line description. Required.",
            "type": "string"
          },
          "date_end": {
            "description": "End of the period this line covers (RFC 3339).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "date_start": {
            "description": "Start of the period this line covers (RFC 3339).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "deductible": {
            "description": "Whether that tax is reclaimable. Omitted defers to the tax type default.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "quantity": {
            "description": "Quantity of units for this line, as a decimal number of units.",
            "format": "double",
            "type": [
              "number",
              "null"
            ]
          },
          "quantity_unit": {
            "description": "Label for the quantity unit.",
            "type": [
              "string",
              "null"
            ]
          },
          "subtotal": {
            "description": "Line subtotal in cents. Required.",
            "format": "int64",
            "type": "integer"
          },
          "tax_amount": {
            "description": "Tax amount for this line in cents.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "tax_type": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/TaxType",
                "description": "Whether the line is cost base (`item`) or tax borne on the purchase,\nreclaimable (`deductible_tax`) or not (`non_deductible_tax`). A\nnon-deductible tax counts towards net expenses, not towards input tax.\nDefaults to `item`."
              }
            ]
          },
          "unit_price": {
            "description": "Unit price in cents.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "unit_unit": {
            "description": "Label for the unit price unit.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "concept",
          "subtotal"
        ],
        "type": "object"
      },
      "ExpenseListItem": {
        "description": "Condensed expense representation for list views.",
        "properties": {
          "category": {
            "description": "Free-form accounting category for the expense.",
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "description": "Creation timestamp (RFC 3339).",
            "format": "date-time",
            "type": "string"
          },
          "currency_code": {
            "description": "ISO 4217 currency code of the expense.",
            "type": "string"
          },
          "expense_date": {
            "description": "Date of the expense (RFC 3339).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "has_receipt": {
            "description": "Whether a receipt file is attached.",
            "type": "boolean"
          },
          "id": {
            "description": "Opaque expense identifier.",
            "type": "string"
          },
          "invoice_reference": {
            "description": "The supplier invoice's own reference/number.",
            "type": "string"
          },
          "line_count": {
            "description": "Number of line items.",
            "format": "int64",
            "type": "integer"
          },
          "supplier_id": {
            "description": "Supplier entity id (the counterparty the bill was received from).",
            "type": "string"
          },
          "supplier_name": {
            "description": "Supplier display name.",
            "type": [
              "string",
              "null"
            ]
          },
          "total": {
            "description": "Total amount in cents, computed from the lines.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "supplier_id",
          "invoice_reference",
          "currency_code",
          "has_receipt",
          "line_count",
          "created_at"
        ],
        "type": "object"
      },
      "ImportInvoiceRequest": {
        "description": "Request to import an invoice that already existed elsewhere.",
        "properties": {
          "bank_account_ids": {
            "description": "Ids of the company's bank accounts to show on the invoice as payment\ninstructions. Unknown ids are ignored.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "currency_code": {
            "description": "ISO 4217 currency. When omitted (or empty) it falls back to the company\ndefault, then the recipient entity's configured currency.",
            "type": [
              "string",
              "null"
            ]
          },
          "custom_placeholder_values": {
            "description": "Per-recipient template placeholder values for this invoice.",
            "items": {
              "$ref": "#/components/schemas/CustomPlaceholderValue"
            },
            "type": "array"
          },
          "exchange_rates": {
            "description": "Frozen exchange rates for any currency pair the effective template uses.",
            "items": {
              "$ref": "#/components/schemas/ExchangeRateEntry"
            },
            "type": "array"
          },
          "invoice_date": {
            "description": "The original issue date; its year places the invoice in reports.",
            "format": "date-time",
            "type": "string"
          },
          "lines": {
            "description": "The invoice line items, exactly as on the original document (amounts are\nused verbatim; no VAT is recomputed). Include tax lines explicitly.",
            "items": {
              "$ref": "#/components/schemas/InvoiceLineRequest"
            },
            "type": "array"
          },
          "recipient_id": {
            "description": "Recipient entity the invoice was billed to.",
            "type": "string"
          },
          "reference": {
            "description": "The original document identifier (any format, e.g. `A/2024/99`).\nMandatory and unique within the company.",
            "type": "string"
          },
          "supply_type": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SupplyType",
                "description": "Whether the lines are goods or services. Defaults to services."
              }
            ]
          }
        },
        "required": [
          "recipient_id",
          "reference",
          "invoice_date",
          "lines"
        ],
        "type": "object"
      },
      "Invoice": {
        "properties": {
          "corrected_invoice_id": {
            "description": "The invoice this one corrects, when it is a corrective invoice.",
            "type": [
              "string",
              "null"
            ]
          },
          "currency_code": {
            "description": "ISO 4217 currency the invoice amounts are expressed in.",
            "type": "string"
          },
          "custom_placeholder_values": {
            "description": "Per-recipient template placeholder values captured on this invoice.",
            "items": {
              "$ref": "#/components/schemas/CustomPlaceholderValue"
            },
            "type": "array"
          },
          "id": {
            "description": "Opaque invoice identifier.",
            "type": "string"
          },
          "invoice_number": {
            "description": "Fiscal invoice number assigned at issue. Null while a draft.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "invoice_year": {
            "description": "Fiscal year of the invoice number, assigned at issue. Null while a draft.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "issued_at": {
            "description": "When the invoice was issued (finalized). Null while a draft.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "lines": {
            "description": "The invoice line items.",
            "items": {
              "$ref": "#/components/schemas/InvoiceLine"
            },
            "type": "array"
          },
          "order_number": {
            "description": "Draft ordering sequence number. Null once issued.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "order_year": {
            "description": "Year the draft ordering sequence belongs to. Null once issued.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "origin": {
            "$ref": "#/components/schemas/InvoiceOrigin",
            "description": "How the invoice came to exist here. Imported invoices are never reported\nto VeriFactu."
          },
          "recipient_id": {
            "description": "Recipient entity the invoice is billed to.",
            "type": "string"
          },
          "reference": {
            "description": "The frozen document reference, once issued: the format-rendered value for\na native invoice, or the original identifier for an imported one. Null\nwhile a draft.",
            "type": [
              "string",
              "null"
            ]
          },
          "supply_type": {
            "$ref": "#/components/schemas/SupplyType",
            "description": "Whether the lines are goods or services."
          },
          "total": {
            "description": "Total in cents (sum of all lines).",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "verifactu": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/InvoiceVerifactu",
                "description": "VeriFactu-specific corrective metadata; present only for corrective invoices."
              }
            ]
          }
        },
        "required": [
          "id",
          "recipient_id",
          "origin",
          "supply_type",
          "lines",
          "custom_placeholder_values",
          "currency_code"
        ],
        "type": "object"
      },
      "InvoiceCounts": {
        "properties": {
          "corrective": {
            "description": "Issued invoices that correct an earlier one.",
            "format": "int64",
            "type": "integer"
          },
          "draft": {
            "description": "Number of draft invoices.",
            "format": "int64",
            "type": "integer"
          },
          "issued": {
            "description": "Number of issued invoices.",
            "format": "int64",
            "type": "integer"
          },
          "proforma": {
            "description": "Number of proforma invoices.",
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "draft",
          "proforma",
          "issued",
          "corrective"
        ],
        "type": "object"
      },
      "InvoiceLine": {
        "properties": {
          "concept": {
            "description": "Free-text description of the line.",
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "description": "When the line was created.",
            "format": "date-time",
            "type": "string"
          },
          "date_end": {
            "description": "End of the service/supply period the line covers.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "date_start": {
            "description": "Start of the service/supply period the line covers.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "deleted_at": {
            "description": "Soft-delete marker; set when the line was removed.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Opaque line identifier.",
            "type": "string"
          },
          "invoice_id": {
            "description": "Invoice this line belongs to.",
            "type": "string"
          },
          "quantity": {
            "description": "Quantity of the item, as a decimal number of units (e.g. `95.6`).",
            "format": "double",
            "type": [
              "number",
              "null"
            ]
          },
          "quantity_unit": {
            "description": "Unit label for the quantity (e.g. \"hours\", \"units\").",
            "type": [
              "string",
              "null"
            ]
          },
          "subtotal": {
            "description": "Line subtotal in cents of the document's currency.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "tax_amount": {
            "description": "Tax amount in cents of the document's currency.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "tax_type": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/TaxType",
                "description": "Whether the line is taxable base (`item`) or the tax charged on it\n(`tax`). Defaults to `item`."
              }
            ]
          },
          "unit_price": {
            "description": "Unit price in cents of the document's currency.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "unit_unit": {
            "description": "Unit label for the unit price.",
            "type": [
              "string",
              "null"
            ]
          },
          "updated_at": {
            "description": "When the line was last updated.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "invoice_id",
          "created_at"
        ],
        "type": "object"
      },
      "InvoiceLineRequest": {
        "properties": {
          "concept": {
            "description": "Free-text description of the line.",
            "type": [
              "string",
              "null"
            ]
          },
          "date_end": {
            "description": "End of the service/supply period the line covers.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "date_start": {
            "description": "Start of the service/supply period the line covers.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "quantity": {
            "description": "Quantity of the item, as a decimal number of units (e.g. `95.6`).",
            "format": "double",
            "type": [
              "number",
              "null"
            ]
          },
          "quantity_unit": {
            "description": "Unit label for the quantity (e.g. \"hours\", \"units\").",
            "type": [
              "string",
              "null"
            ]
          },
          "subtotal": {
            "description": "Line subtotal in cents of the document's currency.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "tax_amount": {
            "description": "Tax amount in cents of the document's currency.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "tax_type": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/TaxType",
                "description": "Whether the line is taxable base (`item`) or the tax charged on it\n(`tax`). Defaults to `item`."
              }
            ]
          },
          "unit_price": {
            "description": "Unit price in cents of the document's currency.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "unit_unit": {
            "description": "Unit label for the unit price.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "InvoiceListItem": {
        "properties": {
          "corrected_invoice_id": {
            "description": "The invoice this one corrects, when it is a corrective invoice.",
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "description": "When the invoice record was created.",
            "format": "date-time",
            "type": "string"
          },
          "currency_code": {
            "description": "ISO 4217 currency the invoice amounts are expressed in.",
            "type": "string"
          },
          "id": {
            "description": "Opaque invoice identifier.",
            "type": "string"
          },
          "invoice_number": {
            "description": "Fiscal invoice number assigned at issue. Null while a draft.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "invoice_year": {
            "description": "Fiscal year of the invoice number, assigned at issue. Null while a draft.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "issued_at": {
            "description": "When the invoice was issued (finalized). Null while a draft.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "line_count": {
            "description": "Number of line items on the invoice.",
            "format": "int64",
            "type": "integer"
          },
          "order_number": {
            "description": "Draft ordering sequence number. Null once issued.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "order_year": {
            "description": "Year the draft ordering sequence belongs to. Null once issued.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "recipient_id": {
            "description": "Recipient entity the invoice is billed to.",
            "type": "string"
          },
          "recipient_name": {
            "description": "Recipient name as this invoice states it, read from the snapshot frozen\nat creation, so a list row keeps saying what the document says even after\nthe entity is renamed.",
            "type": [
              "string",
              "null"
            ]
          },
          "reference": {
            "description": "Human-readable document reference (e.g. `INV-2026-1`, `R-INV-2026-1`,\n`PRO-2026-1`), matching the reference printed on the generated document.\n`None` for drafts that have not been assigned a number yet.",
            "type": [
              "string",
              "null"
            ]
          },
          "total": {
            "description": "Total in cents (sum of all lines).",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "recipient_id",
          "currency_code",
          "created_at",
          "line_count"
        ],
        "type": "object"
      },
      "InvoiceOrigin": {
        "description": "How an invoice came to exist in this system.\n\nThis is a durable fiscal property, not a runtime flag: it gates VeriFactu\nsubmission (only `Native` invoices from an in-scope issuer are remitted) and\nmust never be flipped after creation.",
        "enum": [
          "native",
          "imported"
        ],
        "type": "string"
      },
      "InvoiceTemplateContextResponse": {
        "description": "The dynamic bits of the invoice-creation form for a chosen recipient: the\neffective custom-placeholder definitions and the exchange-rate pairs the\ntemplate needs (rendered as optional \"leave blank to fetch at issue\" inputs).",
        "properties": {
          "custom_placeholders": {
            "description": "The effective custom-placeholder definitions for the chosen recipient.",
            "items": {
              "$ref": "#/components/schemas/CustomPlaceholder"
            },
            "type": "array"
          },
          "required_exchange_rates": {
            "description": "The currency pairs the effective template needs a rate for.",
            "items": {
              "$ref": "#/components/schemas/ExchangeRatePair"
            },
            "type": "array"
          }
        },
        "required": [
          "custom_placeholders",
          "required_exchange_rates"
        ],
        "type": "object"
      },
      "InvoiceVerifactu": {
        "description": "VeriFactu (Spanish AEAT) corrective metadata. VeriFactu is a Spanish\nregime, so this is present only on corrective invoices issued by a Spanish\n(`ES-…`) company; correctives from issuers in other countries carry no\nreason and omit it entirely.\n\nCorrections are always issued *por diferencias* (VeriFactu\n`TipoRectificativa = I`): the amounts on the corrective invoice are the\ncorrection itself. That encoding is not exposed: the only corrective choice\nsurfaced to callers is the legal reason (`R1`–`R5`).",
        "properties": {
          "correction_reason": {
            "$ref": "#/components/schemas/CorrectionReason",
            "description": "The reason the correction is issued."
          }
        },
        "required": [
          "correction_reason"
        ],
        "type": "object"
      },
      "MonthlyRevenue": {
        "properties": {
          "amount_minor": {
            "description": "Revenue for the month, in cents of `primary_currency`.",
            "format": "int64",
            "type": "integer"
          },
          "month": {
            "description": "Month label as `YYYY-MM`.",
            "type": "string"
          }
        },
        "required": [
          "month",
          "amount_minor"
        ],
        "type": "object"
      },
      "OrdinaryInvoice": {
        "description": "An ordinary (non-corrective) invoice.\n\nReturned by the endpoints that only ever produce ordinary invoices (invoice\nand proforma creation, import, and proforma promotion), so it deliberately\nomits the corrective metadata (`corrected_invoice_id`, `verifactu`) that\ncannot apply here. Fetching (`GET /v1/invoices/{id}`) or issuing\n(`POST /v1/invoices/{id}/issue`) an invoice may surface a correction, so\nthose return the richer `Invoice`; corrections themselves return\n`CorrectiveInvoice`.",
        "properties": {
          "currency_code": {
            "description": "ISO 4217 currency the invoice amounts are expressed in.",
            "type": "string"
          },
          "custom_placeholder_values": {
            "description": "Per-recipient template placeholder values captured on this invoice.",
            "items": {
              "$ref": "#/components/schemas/CustomPlaceholderValue"
            },
            "type": "array"
          },
          "id": {
            "description": "Opaque invoice identifier.",
            "type": "string"
          },
          "invoice_number": {
            "description": "Fiscal invoice number assigned at issue. Null while a draft.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "invoice_year": {
            "description": "Fiscal year of the invoice number, assigned at issue. Null while a draft.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "issued_at": {
            "description": "When the invoice was issued (finalized). Null while a draft.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "lines": {
            "description": "The invoice line items.",
            "items": {
              "$ref": "#/components/schemas/InvoiceLine"
            },
            "type": "array"
          },
          "order_number": {
            "description": "Draft ordering sequence number. Null once issued.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "order_year": {
            "description": "Year the draft ordering sequence belongs to. Null once issued.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "origin": {
            "$ref": "#/components/schemas/InvoiceOrigin",
            "description": "How the invoice came to exist here. Imported invoices are never reported\nto VeriFactu."
          },
          "recipient_id": {
            "description": "Recipient entity the invoice is billed to.",
            "type": "string"
          },
          "reference": {
            "description": "The frozen document reference, once issued: the format-rendered value for\na native invoice, or the original identifier for an imported one. Null\nwhile a draft.",
            "type": [
              "string",
              "null"
            ]
          },
          "supply_type": {
            "$ref": "#/components/schemas/SupplyType",
            "description": "Whether the lines are goods or services."
          },
          "total": {
            "description": "Total in cents (sum of all lines).",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "recipient_id",
          "origin",
          "supply_type",
          "lines",
          "custom_placeholder_values",
          "currency_code"
        ],
        "type": "object"
      },
      "PrefillTaxesRequest": {
        "properties": {
          "lines": {
            "description": "The goods/services lines to compute taxes for.",
            "items": {
              "$ref": "#/components/schemas/InvoiceLineRequest"
            },
            "type": "array"
          },
          "recipient_id": {
            "description": "Recipient entity whose tax rules drive the computed tax lines.",
            "type": "string"
          }
        },
        "required": [
          "recipient_id",
          "lines"
        ],
        "type": "object"
      },
      "PrefillTaxesResponse": {
        "properties": {
          "lines": {
            "description": "The input lines augmented with the computed tax lines.",
            "items": {
              "$ref": "#/components/schemas/InvoiceLineRequest"
            },
            "type": "array"
          }
        },
        "required": [
          "lines"
        ],
        "type": "object"
      },
      "Receipt": {
        "description": "Metadata of a receipt file attached to an expense.",
        "properties": {
          "content_type": {
            "description": "MIME content type of the receipt.",
            "type": [
              "string",
              "null"
            ]
          },
          "filename": {
            "description": "Original filename of the receipt.",
            "type": [
              "string",
              "null"
            ]
          },
          "size": {
            "description": "Size of the receipt file in bytes.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "uploaded_at": {
            "description": "Upload timestamp (RFC 3339).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "ReceiptConfirmRequest": {
        "description": "Confirmation of a completed browser-direct receipt upload.",
        "properties": {
          "content_type": {
            "description": "MIME content type of the uploaded receipt.",
            "type": "string"
          },
          "filename": {
            "description": "Original filename of the uploaded receipt.",
            "type": "string"
          },
          "object_key": {
            "description": "Storage key of the uploaded receipt object.",
            "type": "string"
          },
          "size": {
            "description": "Size of the uploaded receipt file in bytes.",
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "object_key",
          "filename",
          "content_type",
          "size"
        ],
        "type": "object"
      },
      "ReceiptDownloadUrlResponse": {
        "description": "Presigned URL for a browser-direct receipt download.",
        "properties": {
          "expires_at": {
            "description": "Expiry of the presigned URL (RFC 3339).",
            "format": "date-time",
            "type": "string"
          },
          "filename": {
            "description": "Original filename of the receipt.",
            "type": "string"
          },
          "url": {
            "description": "Presigned URL the browser GETs the file from (directly from storage).",
            "type": "string"
          }
        },
        "required": [
          "url",
          "filename",
          "expires_at"
        ],
        "type": "object"
      },
      "ReceiptUploadUrlRequest": {
        "description": "Request to obtain a presigned receipt-upload URL.",
        "properties": {
          "content_type": {
            "description": "MIME content type of the receipt to upload.",
            "type": "string"
          },
          "filename": {
            "description": "Original filename of the receipt to upload.",
            "type": "string"
          }
        },
        "required": [
          "filename",
          "content_type"
        ],
        "type": "object"
      },
      "ReceiptUploadUrlResponse": {
        "description": "Presigned URL and object key for a browser-direct receipt upload.",
        "properties": {
          "expires_at": {
            "description": "Expiry of the presigned URL (RFC 3339).",
            "format": "date-time",
            "type": "string"
          },
          "object_key": {
            "description": "Object key to send back when confirming the upload.",
            "type": "string"
          },
          "url": {
            "description": "Presigned URL the browser PUTs the file to (directly to object storage).",
            "type": "string"
          }
        },
        "required": [
          "url",
          "object_key",
          "expires_at"
        ],
        "type": "object"
      },
      "ReportType": {
        "description": "The kind of business report the user requested. Every type is rendered with\nthe same design system; the data and layout differ per type.",
        "enum": [
          "business_overview",
          "vat_summary",
          "profit_loss",
          "client_revenue",
          "expense_supplier"
        ],
        "type": "string",
        "x-enum-varnames": [
          "BusinessOverview",
          "VatSummary",
          "ProfitLoss",
          "ClientRevenue",
          "ExpenseSupplier"
        ]
      },
      "ReportView": {
        "description": "A report and its generation state.",
        "properties": {
          "completed_at": {
            "description": "When generation reached a terminal state (RFC 3339).",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "description": "When the report was requested (RFC 3339).",
            "format": "date-time",
            "type": "string"
          },
          "error": {
            "description": "Diagnostic message, when the report `failed`.",
            "type": [
              "string",
              "null"
            ]
          },
          "filename": {
            "description": "Download filename, once the report is `ready`.",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Opaque report identifier.",
            "type": "string"
          },
          "locale": {
            "description": "The locale the report is rendered in, frozen at request time (`en_US`,\n`es_ES`, …).",
            "type": "string"
          },
          "period_end": {
            "description": "End of the reporting window (RFC 3339).",
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "description": "Start of the reporting window (RFC 3339).",
            "format": "date-time",
            "type": "string"
          },
          "report_type": {
            "description": "Which report this is (`business_overview`, `vat_summary`, …).",
            "type": "string"
          },
          "requested_by": {
            "description": "The platform user who requested the report.",
            "type": "string"
          },
          "requested_by_name": {
            "description": "Display name of the requesting user, when resolvable.",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "description": "Lifecycle status: `pending`, `ready`, or `failed`.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "requested_by",
          "report_type",
          "status",
          "locale",
          "period_start",
          "period_end",
          "created_at"
        ],
        "type": "object"
      },
      "RequestReportRequest": {
        "description": "Payload to request a background-generated report.",
        "properties": {
          "locales": {
            "description": "Locale(s) to render the report in (`en`, `es`, `es_ES`, …). **One report\nis generated per locale.** Numbers are formatted per region, so the same\nlanguage in two regions (`es_ES` vs `es_MX`) can render differently.\nOmitted/empty renders a single report in the requesting user's language.",
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "period_end": {
            "description": "End of the reporting window (RFC 3339, exclusive).",
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "description": "Start of the reporting window (RFC 3339, inclusive).",
            "format": "date-time",
            "type": "string"
          },
          "report_type": {
            "$ref": "#/components/schemas/ReportType",
            "description": "Which report to generate."
          }
        },
        "required": [
          "report_type",
          "period_start",
          "period_end"
        ],
        "type": "object"
      },
      "SupplyType": {
        "description": "Whether an invoice covers services or goods.",
        "enum": [
          "services",
          "goods"
        ],
        "type": "string"
      },
      "TaxType": {
        "description": "The tax a line carries. A line with no tax type is an ordinary\ngoods/services line, represented as `None` rather than a sentinel variant.",
        "enum": [
          "vat",
          "other",
          "es:irpf",
          "es:recargo",
          "es:igic"
        ],
        "type": "string",
        "x-enum-varnames": [
          "Vat",
          "Other",
          "EsIrpf",
          "EsRecargo",
          "EsIgic"
        ]
      },
      "ThirdPartyAddress": {
        "description": "The postal address of a third party (a customer or provider entity).",
        "properties": {
          "city": {
            "description": "City or town.",
            "type": [
              "string",
              "null"
            ]
          },
          "country": {
            "description": "Country: the only address component required for a third party.",
            "type": "string"
          },
          "lines": {
            "description": "Street address lines.",
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "state": {
            "description": "State, province, or region.",
            "type": [
              "string",
              "null"
            ]
          },
          "zipcode": {
            "description": "Postal / ZIP code.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "country"
        ],
        "type": "object"
      },
      "TopCustomer": {
        "properties": {
          "amount_minor": {
            "description": "Total issued revenue for the customer, in cents of `primary_currency`.",
            "format": "int64",
            "type": "integer"
          },
          "invoice_count": {
            "description": "Number of issued invoices for the customer.",
            "format": "int64",
            "type": "integer"
          },
          "name": {
            "description": "Customer name, from the most recent invoice snapshot.",
            "type": "string"
          }
        },
        "required": [
          "name",
          "amount_minor",
          "invoice_count"
        ],
        "type": "object"
      },
      "UpdateBankAccountRequest": {
        "description": "Payload to update a bank account (full replace).",
        "properties": {
          "bank_name": {
            "description": "Institution name.",
            "type": [
              "string",
              "null"
            ]
          },
          "bic": {
            "description": "Bank Identifier Code / SWIFT.",
            "type": [
              "string",
              "null"
            ]
          },
          "currency_code": {
            "description": "ISO 4217 currency code of the account.",
            "type": "string"
          },
          "iban": {
            "description": "International Bank Account Number.",
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "description": "User-facing label for the account.",
            "type": "string"
          }
        },
        "required": [
          "name",
          "currency_code"
        ],
        "type": "object"
      },
      "UpdateCompanyConfigurationRequest": {
        "properties": {
          "address": {
            "$ref": "#/components/schemas/Address",
            "description": "Company postal address."
          },
          "correctiveInvoiceReferenceFormat": {
            "description": "Format for the frozen reference of corrective invoices; must use\n`{year}` and `{number}` (e.g. `R-INV-{year}-{number}`).",
            "type": "string"
          },
          "currencyCode": {
            "description": "ISO 4217 default currency for the company.",
            "type": [
              "string",
              "null"
            ]
          },
          "customPlaceholders": {
            "description": "Custom placeholder definitions available to the templates.",
            "items": {
              "$ref": "#/components/schemas/CustomPlaceholder"
            },
            "type": "array"
          },
          "email": {
            "description": "Primary contact email.",
            "type": "string"
          },
          "firstCorrectiveInvoiceYearlyNumber": {
            "description": "Starting sequence number for the first corrective invoice of each year.",
            "format": "int64",
            "type": "integer"
          },
          "firstInvoiceYearlyNumber": {
            "description": "Starting sequence number for the first invoice of each year.",
            "format": "int64",
            "type": "integer"
          },
          "footerInvoiceTypst": {
            "description": "Typst snippet rendered in the invoice footer.",
            "type": [
              "string",
              "null"
            ]
          },
          "invoiceReferenceFormat": {
            "description": "Format for the frozen reference of regular invoices; must use `{year}`\nand `{number}` (e.g. `INV-{year}-{number}`).",
            "type": "string"
          },
          "phone": {
            "description": "Primary contact phone.",
            "type": "string"
          },
          "postInvoiceTypst": {
            "description": "Typst snippet appended after the invoice body.",
            "type": [
              "string",
              "null"
            ]
          },
          "proformaReferenceFormat": {
            "description": "Format for the frozen reference of proformas; must use `{year}` and\n`{number}` (e.g. `PRO-{year}-{number}`).",
            "type": "string"
          }
        },
        "required": [
          "email",
          "phone",
          "address",
          "firstInvoiceYearlyNumber",
          "firstCorrectiveInvoiceYearlyNumber",
          "invoiceReferenceFormat",
          "correctiveInvoiceReferenceFormat",
          "proformaReferenceFormat"
        ],
        "type": "object"
      },
      "UpdateCompanyUserRequest": {
        "properties": {
          "expiresAt": {
            "description": "RFC 3339 timestamp when access should end; `null` means never.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "UpdateCurrentUserRequest": {
        "properties": {
          "language": {
            "description": "Preferred UI language; empty clears the preference.",
            "type": "string"
          }
        },
        "required": [
          "language"
        ],
        "type": "object"
      },
      "UpdateEntityRequest": {
        "description": "Payload to update an existing entity.",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/ThirdPartyAddress",
            "description": "Postal address; its country is mandatory."
          },
          "currency_code": {
            "description": "ISO 4217 currency code; defaults to the company currency when omitted.",
            "type": [
              "string",
              "null"
            ]
          },
          "fiscal_id": {
            "description": "Tax identifier (NIF/VAT number/etc.).",
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "description": "Display name of the entity.",
            "type": "string"
          },
          "template": {
            "$ref": "#/components/schemas/EntityTemplate",
            "description": "Per-recipient Typst template overrides and custom placeholders."
          },
          "type": {
            "description": "Entity type/country-prefixed kind (drives legal placement).",
            "type": "string"
          },
          "verifactu": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/EntityVerifactu",
                "description": "VeriFactu-specific settings for this entity."
              }
            ]
          },
          "vies_vat_id": {
            "description": "VIES-registered intra-EU VAT number.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "name",
          "type",
          "address"
        ],
        "type": "object"
      },
      "VerifactuAuthorization": {
        "description": "One taxpayer's VeriFactu authorization state. No recorded authorization is\nequivalent to \"not authorized\".",
        "properties": {
          "company_id": {
            "description": "Id of the taxpayer's company.",
            "type": "string"
          },
          "fiscal_id": {
            "description": "NIF of the taxpayer, from its company.",
            "type": "string"
          },
          "granted_at": {
            "description": "RFC 3339 timestamp when the power was confirmed granted.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "last_aeat_check": {
            "description": "RFC 3339 timestamp of the last AEAT status check.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "$ref": "#/components/schemas/VerifactuAuthorizationStatus",
            "description": "Current authorization status for this taxpayer."
          }
        },
        "required": [
          "company_id",
          "fiscal_id",
          "status"
        ],
        "type": "object"
      },
      "VerifactuAuthorizationStatus": {
        "description": "Status of a taxpayer's AEAT power of attorney (*apoderamiento*) towards\nuninvoice.app.\n\nuninvoice.app remits VeriFactu records only via that power (it is not a\nTipo 017 social collaborator). A Spanish (in-scope) issuer may only issue\ninvoices once its power is [`Active`](Self::Active); the AEAT itself remains\nthe authoritative check at submission time (errors 4105/4112).",
        "enum": [
          "NotGranted",
          "Pending",
          "Active",
          "Revoked"
        ],
        "type": "string"
      }
    }
  },
  "info": {
    "description": "Handle invoices and accounting in an easy and intuitive way",
    "license": {
      "name": "Apache-2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.txt"
    },
    "title": "uninvoice",
    "version": "1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/v1/ai-audit": {
      "get": {
        "description": "Optionally filtered by status (`pending`, `approved`, `rejected`, `failed`).",
        "operationId": "list-ai-audit",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Filter by status: pending, approved, rejected, failed",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/AiAuditEntry"
                  },
                  "type": "array"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "List captured AI actions for the company",
        "tags": [
          "AI Audit"
        ]
      }
    },
    "/v1/ai-audit/approve": {
      "post": {
        "description": "Approve several pending AI-requested actions: each original request is replayed and executed. **Human-only**: the caller must present a valid `X-Human-Proof` (the API token's `human_proof` secret); an API-token caller without it is refused with `403`.",
        "operationId": "bulk-approve-ai-audit-entries",
        "parameters": [
          {
            "description": "Bearer session token driving the request",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The API token's `human_proof` secret (returned once when the token was minted); present it to prove a human is driving this review.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkIdsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkActionResult"
                }
              }
            },
            "description": ""
          },
          "403": {
            "description": "Caller is not human (no valid X-Human-Proof)"
          }
        },
        "summary": "Approve several pending AI-requested actions at once",
        "tags": [
          "AI Audit"
        ]
      }
    },
    "/v1/ai-audit/reject": {
      "post": {
        "description": "Reject several pending AI-requested actions: nothing is executed and each entry is marked `rejected`. **Human-only**: the caller must present a valid `X-Human-Proof` (the API token's `human_proof` secret); an API-token caller without it is refused with `403`.",
        "operationId": "bulk-reject-ai-audit-entries",
        "parameters": [
          {
            "description": "Bearer session token driving the request",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The API token's `human_proof` secret (returned once when the token was minted); present it to prove a human is driving this review.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkIdsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkActionResult"
                }
              }
            },
            "description": ""
          },
          "403": {
            "description": "Caller is not human (no valid X-Human-Proof)"
          }
        },
        "summary": "Reject several pending AI-requested actions at once",
        "tags": [
          "AI Audit"
        ]
      }
    },
    "/v1/ai-audit/{id}": {
      "get": {
        "operationId": "get-ai-audit-entry",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit entry ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiAuditEntry"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "Get a single captured AI action by id",
        "tags": [
          "AI Audit"
        ]
      }
    },
    "/v1/ai-audit/{id}/approve": {
      "post": {
        "description": "Approve a pending AI-requested action: the original request is replayed and executed. **Human-only**: the caller must present a valid `X-Human-Proof` (the API token's `human_proof` secret); an API-token caller without it is refused with `403`.",
        "operationId": "approve-ai-audit-entry",
        "parameters": [
          {
            "description": "Bearer session token driving the request",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The API token's `human_proof` secret (returned once when the token was minted); present it to prove a human is driving this review.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "description": "AI Audit entry ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiAuditEntry"
                }
              }
            },
            "description": ""
          },
          "403": {
            "description": "Caller is not human (no valid X-Human-Proof)"
          }
        },
        "tags": [
          "AI Audit"
        ]
      }
    },
    "/v1/ai-audit/{id}/reject": {
      "post": {
        "description": "Reject a pending AI-requested action: nothing is executed and the entry is marked `rejected`. **Human-only**: the caller must present a valid `X-Human-Proof` (the API token's `human_proof` secret); an API-token caller without it is refused with `403`.",
        "operationId": "reject-ai-audit-entry",
        "parameters": [
          {
            "description": "Bearer session token driving the request",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The API token's `human_proof` secret (returned once when the token was minted); present it to prove a human is driving this review.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "description": "AI Audit entry ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiAuditEntry"
                }
              }
            },
            "description": ""
          },
          "403": {
            "description": "Caller is not human (no valid X-Human-Proof)"
          }
        },
        "tags": [
          "AI Audit"
        ]
      }
    },
    "/v1/bank-accounts": {
      "delete": {
        "description": "Takes an `ids` body (`DELETE` with a payload). Ids that don't resolve for\nthis company are skipped; the response reports how many were deleted.",
        "operationId": "bulk-delete-bank-accounts",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkIdsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkActionResult"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Delete several bank accounts at once",
        "tags": [
          "Bank Accounts"
        ]
      },
      "get": {
        "operationId": "list-bank-accounts",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/BankAccountView"
                  },
                  "type": "array"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "List the current company's bank accounts (with balances)",
        "tags": [
          "Bank Accounts"
        ]
      },
      "post": {
        "operationId": "create-bank-account",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBankAccountRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccountView"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Create a bank account for the current company",
        "tags": [
          "Bank Accounts"
        ]
      }
    },
    "/v1/bank-accounts/{id}": {
      "delete": {
        "operationId": "delete-bank-account",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Bank account ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          },
          "204": {
            "description": ""
          }
        },
        "summary": "Delete a bank account",
        "tags": [
          "Bank Accounts"
        ]
      },
      "get": {
        "operationId": "get-bank-account",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Bank account ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccountDetail"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "Get a bank account with its balance-snapshot history",
        "tags": [
          "Bank Accounts"
        ]
      },
      "put": {
        "operationId": "update-bank-account",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Bank account ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateBankAccountRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccountView"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Update a bank account",
        "tags": [
          "Bank Accounts"
        ]
      }
    },
    "/v1/bank-accounts/{id}/main": {
      "put": {
        "description": "Clears the previous default and marks this account as the one pre-selected\nwherever an account is picked (e.g. invoice payment details).",
        "operationId": "set-main-bank-account",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Bank account ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BankAccountView"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Make a bank account the company's default",
        "tags": [
          "Bank Accounts"
        ]
      }
    },
    "/v1/bank-accounts/{id}/snapshots": {
      "get": {
        "operationId": "list-balance-snapshots",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Bank account ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/BalanceSnapshotView"
                  },
                  "type": "array"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "List a bank account's balance snapshots (newest first)",
        "tags": [
          "Bank Accounts"
        ]
      },
      "post": {
        "operationId": "create-balance-snapshot",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Bank account ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBalanceSnapshotRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BalanceSnapshotView"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Record a balance snapshot for a bank account",
        "tags": [
          "Bank Accounts"
        ]
      }
    },
    "/v1/bank-accounts/{id}/snapshots/{snapshot_id}": {
      "delete": {
        "operationId": "delete-balance-snapshot",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Bank account ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Balance snapshot ID",
            "in": "path",
            "name": "snapshot_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          },
          "204": {
            "description": ""
          }
        },
        "summary": "Delete a bank account's balance snapshot",
        "tags": [
          "Bank Accounts"
        ]
      }
    },
    "/v1/companies/current": {
      "get": {
        "operationId": "get-current-company",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyConfiguration"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "Retrieve the authenticated user's company configuration",
        "tags": [
          "Company"
        ]
      },
      "put": {
        "operationId": "update-current-company",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCompanyConfigurationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyConfiguration"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Update company configuration including contact info, address, and invoice settings",
        "tags": [
          "Company"
        ]
      }
    },
    "/v1/companies/current/complete": {
      "put": {
        "description": "Requires authentication and agreement to the ToS/Privacy Policy, but not\ncompany settlement.",
        "operationId": "complete-company-registration",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompleteCompanyRegistrationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Company"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Complete company registration for the current user",
        "tags": [
          "Company"
        ]
      }
    },
    "/v1/companies/current/users": {
      "get": {
        "description": "Includes memberships whose access is currently withdrawn or lapsed: they are\nthe company's to restore, so they stay on the list.",
        "operationId": "list-company-users",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/CompanyUser"
                  },
                  "type": "array"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "List who may access the active company",
        "tags": [
          "Company Users"
        ]
      },
      "post": {
        "description": "Membership is roleless: everyone admitted gets full access. Re-admitting an\naddress whose access was withdrawn restores that membership, keeping the\ndate it was first granted.",
        "operationId": "add-company-user",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddCompanyUserRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyUser"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Admit someone to the active company",
        "tags": [
          "Company Users"
        ]
      }
    },
    "/v1/companies/current/users/{user_email}": {
      "put": {
        "operationId": "update-company-user",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Email of the member",
            "in": "path",
            "name": "user_email",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCompanyUserRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyUser"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Set when a member's access ends",
        "tags": [
          "Company Users"
        ]
      }
    },
    "/v1/companies/current/users/{user_email}/deactivate": {
      "post": {
        "description": "Reversible, and scoped to this company: an address that other companies also\nadmitted keeps their books. Nothing is deleted, so the membership stays\nlisted and can be reactivated with its original date.",
        "operationId": "deactivate-company-user",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Email of the member",
            "in": "path",
            "name": "user_email",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyUser"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Withdraw a member's access to the active company",
        "tags": [
          "Company Users"
        ]
      }
    },
    "/v1/companies/current/users/{user_email}/reactivate": {
      "post": {
        "operationId": "reactivate-company-user",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Email of the member",
            "in": "path",
            "name": "user_email",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyUser"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Give a withdrawn member their access back",
        "tags": [
          "Company Users"
        ]
      }
    },
    "/v1/companies/current/users/{user_email}/rotate-password": {
      "post": {
        "description": "The current password cannot be re-sent: only its hash is stored. Rotating is\nwhat a lost credential gets, and the member may equally do it themselves\nthrough the forgot-password form.",
        "operationId": "rotate-company-user-password",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Email of the member",
            "in": "path",
            "name": "user_email",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          },
          "204": {
            "description": "New password generated and queued for delivery"
          }
        },
        "summary": "Replace a password member's password and mail them the new one",
        "tags": [
          "Company Users"
        ]
      }
    },
    "/v1/dashboard": {
      "get": {
        "operationId": "dashboard",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Dashboard"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "Get aggregate figures for the active company's dashboard",
        "tags": [
          "Dashboard"
        ]
      }
    },
    "/v1/entities": {
      "delete": {
        "description": "Takes an `ids` body (`DELETE` with a payload). Ids that don't resolve for\nthis company, and entities already deleted, are skipped; the response\nreports how many were actually deleted.",
        "operationId": "bulk-delete-entities",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkIdsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkActionResult"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Delete several entities at once",
        "tags": [
          "Entities"
        ]
      },
      "get": {
        "operationId": "list-entities",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Entity"
                  },
                  "type": "array"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "List all entities for the current company",
        "tags": [
          "Entities"
        ]
      },
      "post": {
        "operationId": "create-entity",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateEntityRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Entity"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Create an entity for the current company",
        "tags": [
          "Entities"
        ]
      }
    },
    "/v1/entities/{id}": {
      "delete": {
        "description": "The entity stops being listed and can no longer be picked for a new\ndocument; invoices and expenses already issued to it are untouched, since\nthey carry their own snapshot of its data.",
        "operationId": "delete-entity",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Entity ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          },
          "204": {
            "description": ""
          }
        },
        "summary": "Delete an entity",
        "tags": [
          "Entities"
        ]
      },
      "get": {
        "operationId": "get-entity",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Entity ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Entity"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "Get an entity by id",
        "tags": [
          "Entities"
        ]
      },
      "put": {
        "operationId": "update-entity",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Entity ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateEntityRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Entity"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Update an existing entity",
        "tags": [
          "Entities"
        ]
      }
    },
    "/v1/entities/{id}/expenses": {
      "get": {
        "operationId": "list-entity-expenses",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Entity ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/ExpenseListItem"
                  },
                  "type": "array"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "List the expenses received from a given supplier entity",
        "tags": [
          "Entities"
        ]
      }
    },
    "/v1/entities/{id}/invoices": {
      "get": {
        "operationId": "list-entity-invoices",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Entity ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/InvoiceListItem"
                  },
                  "type": "array"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "List the invoices emitted to a given recipient entity",
        "tags": [
          "Entities"
        ]
      }
    },
    "/v1/expenses": {
      "delete": {
        "description": "Takes an `ids` body (`DELETE` with a payload). Ids that don't resolve for\nthis company are skipped; the response reports how many were deleted.",
        "operationId": "bulk-delete-expenses",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkIdsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkActionResult"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Delete several expenses at once",
        "tags": [
          "Expenses"
        ]
      },
      "get": {
        "operationId": "list-expenses",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/ExpenseListItem"
                  },
                  "type": "array"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "List expenses for the current company",
        "tags": [
          "Expenses"
        ]
      },
      "post": {
        "operationId": "create-expense",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateExpenseRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Expense"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Create an expense for the current company",
        "tags": [
          "Expenses"
        ]
      }
    },
    "/v1/expenses/{id}": {
      "delete": {
        "operationId": "delete-expense",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Expense ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          },
          "204": {
            "description": ""
          }
        },
        "summary": "Delete an expense",
        "tags": [
          "Expenses"
        ]
      },
      "get": {
        "operationId": "get-expense",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Expense ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Expense"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "Get an expense by id",
        "tags": [
          "Expenses"
        ]
      }
    },
    "/v1/expenses/{id}/receipt": {
      "put": {
        "operationId": "confirm-receipt",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Expense ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReceiptConfirmRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Expense"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Confirm a completed receipt upload and attach it to the expense",
        "tags": [
          "Expenses"
        ]
      }
    },
    "/v1/expenses/{id}/receipt/download-url": {
      "get": {
        "description": "Returns a short-lived presigned URL; the browser GETs the receipt bytes\ndirectly from object storage, never through the backend.",
        "operationId": "receipt-download-url",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Expense ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReceiptDownloadUrlResponse"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "Get a presigned URL to download an expense receipt",
        "tags": [
          "Expenses"
        ]
      }
    },
    "/v1/expenses/{id}/receipt/upload-url": {
      "post": {
        "description": "Returns a short-lived presigned URL; the browser PUTs the receipt bytes\ndirectly to object storage, never through the backend.",
        "operationId": "receipt-upload-url",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Expense ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReceiptUploadUrlRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReceiptUploadUrlResponse"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Get a presigned URL to upload an expense receipt",
        "tags": [
          "Expenses"
        ]
      }
    },
    "/v1/invoices": {
      "get": {
        "operationId": "list-invoices",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/InvoiceListItem"
                  },
                  "type": "array"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "List the company's invoices",
        "tags": [
          "Invoices"
        ]
      },
      "post": {
        "description": "Creates an ordinary invoice. To correct an existing invoice, use\n`POST /v1/invoices/{id}/corrections` (or the full-reversal shortcut\n`POST /v1/invoices/{id}/correct`).",
        "operationId": "create-invoice",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInvoiceRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrdinaryInvoice"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Create a draft invoice",
        "tags": [
          "Invoices"
        ]
      }
    },
    "/v1/invoices/download": {
      "get": {
        "description": "Selects the ids given in `?ids=a,b,c`; ids that don't resolve for this\ncompany are dropped from the archive. Drafts bundle their watermarked\npreview, exactly as the single-invoice download does.",
        "operationId": "bulk-download-invoices",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated document ids to bundle, e.g. `ids=abc,def`.",
            "in": "query",
            "name": "ids",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ZIP archive of the selected invoice PDFs"
          }
        },
        "summary": "Download several invoice PDFs as a single ZIP",
        "tags": [
          "Invoices"
        ]
      }
    },
    "/v1/invoices/import": {
      "post": {
        "description": "Records an invoice that was created (and, where applicable, already reported)\nelsewhere. It is stored *issued* with its original `reference` and date, so\nit counts towards reports and totals. The `reference` must be unique within\nthe company.\n\n**Spain-incorporated companies:** an imported invoice is **never** submitted\nto VeriFactu; it is treated as already reported at its origin.",
        "operationId": "import-invoice",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImportInvoiceRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrdinaryInvoice"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Import an already-existing invoice",
        "tags": [
          "Invoices"
        ]
      }
    },
    "/v1/invoices/template-context": {
      "get": {
        "description": "Returns the effective custom-placeholder definitions and the exchange-rate\npairs the recipient's template needs, which drive the adaptive\ninvoice-creation form.",
        "operationId": "get-template-context",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Recipient entity ID",
            "in": "query",
            "name": "recipient_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InvoiceTemplateContextResponse"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "Fetch the dynamic invoice-form context for a recipient",
        "tags": [
          "Invoices"
        ]
      }
    },
    "/v1/invoices/{id}": {
      "get": {
        "operationId": "get-invoice",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Invoice ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "Fetch a single invoice by ID",
        "tags": [
          "Invoices"
        ]
      }
    },
    "/v1/invoices/{id}/correct": {
      "post": {
        "description": "Convenience wrapper over `POST /v1/invoices/{id}/corrections` for the most\ncommon correction: it copies every line of the source invoice with\n**negated amounts** (a complete reversal). The source invoice must be issued\nand not cancelled. Takes no body.\n\nWhen you need a partial correction, or corrective lines that differ from the\noriginal, use `POST /v1/invoices/{id}/corrections`.",
        "operationId": "correct-invoice",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Invoice ID to correct",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CorrectiveInvoice"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Create a corrective invoice that fully reverses an issued invoice",
        "tags": [
          "Invoices"
        ]
      }
    },
    "/v1/invoices/{id}/corrections": {
      "post": {
        "description": "The new invoice corrects the invoice named in the path, which must be\nfinalized (issued) and not cancelled. Its recipient and currency are\ninherited from the corrected invoice and cannot be changed. Supply type,\nlines, custom placeholder values and exchange rates default to the corrected\ninvoice's but may be overridden in the body; an empty `lines` list copies\nthe corrected invoice's lines with negated amounts (a full reversal).",
        "operationId": "create-corrective-invoice",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Invoice ID being corrected",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCorrectiveInvoiceRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CorrectiveInvoice"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Create a corrective invoice for an existing invoice",
        "tags": [
          "Invoices"
        ]
      }
    },
    "/v1/invoices/{id}/issue": {
      "post": {
        "description": "Assigns the fiscal invoice number and freezes the document; any missing\nexchange rates are fetched at this point.",
        "operationId": "issue-invoice",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Invoice ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invoice"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Issue (finalize) a draft invoice",
        "tags": [
          "Invoices"
        ]
      }
    },
    "/v1/invoices/{id}/pdf": {
      "get": {
        "operationId": "download-invoice",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Invoice ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/PdfResponse"
          }
        },
        "summary": "Download an invoice PDF",
        "tags": [
          "Invoices"
        ]
      }
    },
    "/v1/proformas": {
      "delete": {
        "description": "Takes an `ids` body (`DELETE` with a payload). Unknown ids, and proformas\nthat were already promoted (and so can't be deleted), are skipped; the\nresponse reports how many were actually deleted.",
        "operationId": "bulk-delete-proformas",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkIdsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkActionResult"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Delete several proformas at once",
        "tags": [
          "Proformas"
        ]
      },
      "get": {
        "operationId": "list-proformas",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/InvoiceListItem"
                  },
                  "type": "array"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "List the company's proformas",
        "tags": [
          "Proformas"
        ]
      },
      "post": {
        "operationId": "create-proforma",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInvoiceRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrdinaryInvoice"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Create a proforma invoice",
        "tags": [
          "Proformas"
        ]
      }
    },
    "/v1/proformas/download": {
      "get": {
        "description": "Selects the ids given in `?ids=a,b,c`; ids that don't resolve for this\ncompany are dropped from the archive.",
        "operationId": "bulk-download-proformas",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated document ids to bundle, e.g. `ids=abc,def`.",
            "in": "query",
            "name": "ids",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ZIP archive of the selected proforma PDFs"
          }
        },
        "summary": "Download several proforma PDFs as a single ZIP",
        "tags": [
          "Proformas"
        ]
      }
    },
    "/v1/proformas/promote": {
      "post": {
        "description": "Runs the same issue flow as the single-proforma promotion for each id.\nUnknown ids, and proformas that were already promoted, are skipped; the\nresponse reports how many were promoted. A real failure (e.g. the VeriFactu\nauthorization gate) aborts the batch and is surfaced, leaving the proformas\npromoted so far promoted.",
        "operationId": "bulk-promote-proformas",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkIdsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkActionResult"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Promote several proformas at once",
        "tags": [
          "Proformas"
        ]
      }
    },
    "/v1/proformas/{id}": {
      "delete": {
        "operationId": "delete-proforma",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Proforma ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          },
          "204": {
            "description": ""
          }
        },
        "summary": "Delete a proforma",
        "tags": [
          "Proformas"
        ]
      },
      "get": {
        "operationId": "get-proforma",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Proforma ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrdinaryInvoice"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "Fetch a single proforma by ID",
        "tags": [
          "Proformas"
        ]
      }
    },
    "/v1/proformas/{id}/pdf": {
      "get": {
        "operationId": "download-proforma",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Proforma invoice ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/PdfResponse"
          }
        },
        "summary": "Download a proforma PDF",
        "tags": [
          "Proformas"
        ]
      }
    },
    "/v1/proformas/{id}/promote": {
      "post": {
        "description": "Converts the proforma into an ordinary draft invoice, which can then be\nissued.",
        "operationId": "promote-proforma",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Proforma invoice ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrdinaryInvoice"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Promote a proforma to a draft invoice",
        "tags": [
          "Proformas"
        ]
      }
    },
    "/v1/reports": {
      "delete": {
        "description": "Takes an `ids` body (`DELETE` with a payload). Ids that don't resolve for\nthis company are ignored; the response reports how many were actually\ndeleted.",
        "operationId": "bulk-delete-reports",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkIdsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkActionResult"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Delete several reports for the current company",
        "tags": [
          "Reports"
        ]
      },
      "get": {
        "operationId": "list-reports",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/ReportView"
                  },
                  "type": "array"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "List reports for the current company",
        "tags": [
          "Reports"
        ]
      },
      "post": {
        "description": "Returns one [`ReportView`] per requested locale (one report is generated per\nlocale); a single-locale request yields a one-element list.",
        "operationId": "request-report",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestReportRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/ReportView"
                  },
                  "type": "array"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Request a report for the current company",
        "tags": [
          "Reports"
        ]
      }
    },
    "/v1/reports/download": {
      "get": {
        "description": "Selects the ids given in `?ids=a,b,c`; ids that aren't ready (still pending,\nfailed, unknown, or another company's) are dropped from the archive.",
        "operationId": "bulk-download-reports",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated document ids to bundle, e.g. `ids=abc,def`.",
            "in": "query",
            "name": "ids",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ZIP archive of the selected report PDFs"
          }
        },
        "summary": "Download several report PDFs as a single ZIP",
        "tags": [
          "Reports"
        ]
      }
    },
    "/v1/reports/{id}": {
      "delete": {
        "operationId": "delete-report",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Report ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          },
          "204": {
            "description": "Report deleted"
          }
        },
        "summary": "Delete a report for the current company",
        "tags": [
          "Reports"
        ]
      },
      "get": {
        "operationId": "get-report",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Report ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportView"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "Get a single report's status",
        "tags": [
          "Reports"
        ]
      }
    },
    "/v1/reports/{id}/pdf": {
      "get": {
        "operationId": "download-report",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Report ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/PdfResponse"
          }
        },
        "summary": "Download a report PDF",
        "tags": [
          "Reports"
        ]
      }
    },
    "/v1/taxes/prefill": {
      "post": {
        "description": "Returns the input lines augmented with the tax lines derived from the\nrecipient's applicable tax rules.",
        "operationId": "prefill-taxes",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PrefillTaxesRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrefillTaxesResponse"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Compute tax lines for a set of invoice lines",
        "tags": [
          "Invoices"
        ]
      }
    },
    "/v1/users/current": {
      "put": {
        "operationId": "update-current-user",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCurrentUserRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CurrentSession"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Update the signed-in user's own profile",
        "tags": [
          "User"
        ]
      }
    },
    "/v1/verifactu/authorization": {
      "get": {
        "description": "Always responds `200`: the request authenticated and succeeded, so \"no power\ngranted yet\" is a valid state, not an error. When no\nauthorization row exists, the body carries `status: \"not_granted\"` (a\nfirst-class status alongside `pending`/`active`/`revoked`), never a `404`\n(which would read as \"this endpoint does not exist\") or a `403` (which would\nimply the caller isn't allowed here; it is).",
        "operationId": "get-authorization",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifactuAuthorization"
                }
              }
            },
            "description": ""
          }
        },
        "summary": "Return the current VeriFactu authorization status for the acting company",
        "tags": [
          "VeriFactu"
        ]
      }
    },
    "/v1/verifactu/authorization/confirm": {
      "post": {
        "description": "Records the company's claim that it granted the power and returns\nwith status `pending`: the claim alone does not lift the issuance gate. Only\nthe daily reconciliation against the AEAT promotes the authorization to\n`active`. Idempotent: re-confirming restarts the verification.\n\nThis endpoint does **not** contact the AEAT itself: the verification is a\nscheduled, auditable activity, so confirming here returns immediately and\nthe status changes once the next reconciliation runs.",
        "operationId": "confirm-authorization",
        "parameters": [
          {
            "description": "Bearer session token",
            "in": "header",
            "name": "Authorization",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "AI Audit gate. Present the token's `human_proof` secret (returned once when the token was minted) to execute this mutation immediately as a human-driven action. Without it (or with an invalid value) the request is NOT executed: it is recorded in the AI Audit backlog and returns `202 pending_approval` for a human to approve.",
            "in": "header",
            "name": "X-Human-Proof",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifactuAuthorization"
                }
              }
            },
            "description": ""
          },
          "202": {
            "description": "AI-requested mutation recorded for human approval (AI Audit): the action has NOT run. A human approves (replays) or rejects it via the AI Audit endpoints. Body: `{ \"status\": \"pending_approval\", \"auditId\": \"…\" }`."
          }
        },
        "summary": "Confirm the AEAT power of attorney granted by the acting company",
        "tags": [
          "VeriFactu"
        ]
      }
    }
  },
  "servers": [
    {
      "description": "Production",
      "url": "https://api.uninvoice.app"
    }
  ],
  "tags": [
    {
      "description": "Your company's configuration.",
      "name": "Company"
    },
    {
      "description": "Members of your company.",
      "name": "Company Users"
    },
    {
      "description": "Clients and suppliers you invoice or are invoiced by.",
      "name": "Entities"
    },
    {
      "description": "Create, issue, correct, and download invoices.",
      "name": "Invoices"
    },
    {
      "description": "Non-fiscal quotes; promote them into invoices.",
      "name": "Proformas"
    },
    {
      "description": "Bills received from suppliers, with receipts.",
      "name": "Expenses"
    },
    {
      "description": "Your company's bank accounts and balance snapshots.",
      "name": "Bank Accounts"
    },
    {
      "description": "Background-generated PDF business reports.",
      "name": "Reports"
    },
    {
      "description": "Review and approve/reject AI-requested mutations.",
      "name": "AI Audit"
    },
    {
      "description": "Spanish AEAT authorization (Veri*Factu) status.",
      "name": "VeriFactu"
    },
    {
      "description": "Your user profile, and the ways you can sign in to it.",
      "name": "User"
    },
    {
      "description": "Aggregate dashboard data.",
      "name": "Dashboard"
    }
  ]
}