{
  "openapi": "3.1.0",
  "info": {
    "title": "InvoiceXpress API",
    "description": "The InvoiceXpress v3 API: invoicing documents (invoices, guides, estimates) and\ntheir series, clients, items, taxes, schedules and favorites; account, user,\nAT-communication and payment-service settings; batch CSV imports of invoices,\nproducts and clients; dashboard KPIs, reports, SAF-T export, digital signatures,\nEDI (CIUS-PT), Social Security declarations, and reference lists (currencies, tax\ncountries, phone calling codes).\n\nWhat changed between versions of this reference is listed under\n**Changelog**, at the end of the navigation.\n\n## Authentication\n\nSend your `api_key` as a query parameter on JSON (or XML) requests. A request with\nno valid `api_key` answers `401`. The `Authorization: Bearer` and `X-Account`\nheaders authenticate the InvoiceXpress web app only; they are not meant for API\nclients. Endpoints marked as public need no key.\n",
    "version": "3.1.0",
    "contact": {
      "name": "InvoiceXpress API Support",
      "email": "support@invoicexpress.com"
    },
    "x-logo": {
      "url": "../images/ix-logo.svg",
      "altText": "InvoiceXpress Logo"
    }
  },
  "servers": [
    {
      "url": "https://api-v3.app.invoicexpress.com",
      "description": "Production Server"
    }
  ],
  "tags": [
    {
      "name": "Invoices",
      "description": "Create invoices, invoice receipts, simplified invoices, vat moss invoices, credit notes & debit notes and send them to your clients."
    },
    {
      "name": "Guides",
      "description": "Create shippings, transports & devolutions and send them to your clients."
    },
    {
      "name": "Estimates",
      "description": "Create quotes, proformas and fees notes and send them to your clients."
    },
    {
      "name": "Sequences",
      "description": "A Sequence is used to group invoices in a sequential order."
    },
    {
      "name": "Clients",
      "description": "A Client is an entity you send invoices to."
    },
    {
      "name": "Accounts",
      "description": "Manage your InvoiceXpress account settings, users, AT communication, and billing."
    },
    {
      "name": "Account Credentials",
      "description": "Manage AT communication credentials for your account."
    },
    {
      "name": "Collection Alerts",
      "description": "Configure automated payment collection alerts sent to clients."
    },
    {
      "name": "Batch Invoices",
      "description": "Bulk-create invoices from a CSV file. Flow — GET batch → upload → process → mapping → configure_options → configure → validate → validation → available_docs → POST create → status. DELETE to discard.\n"
    },
    {
      "name": "Batch Products",
      "description": "Bulk import products from a CSV file. Flow — GET index (optional) → upload → process → GET/PUT mapping → validate → validation → POST create → status. DELETE to discard.\n"
    },
    {
      "name": "Batch Clients",
      "description": "Bulk import clients from a CSV file. Flow — GET index (optional) → upload → process → GET/PUT mapping → validate → validation → POST create → status. DELETE to discard. No configure step.\n"
    },
    {
      "name": "Items",
      "description": "An Item is the product or service you invoice."
    },
    {
      "name": "Schedules",
      "description": "Create and manage recurring document schedules."
    },
    {
      "name": "Taxes",
      "description": "Manage tax rates for your account."
    },
    {
      "name": "Current User",
      "description": "Manage the currently authenticated user's own profile, API key, linked accounts, and password recovery."
    },
    {
      "name": "Currencies",
      "description": "List supported currencies and look up exchange rates between them."
    },
    {
      "name": "Dashboard",
      "description": "Retrieve dashboard KPIs and analytics about your clients and invoicing activity."
    },
    {
      "name": "Favorites",
      "description": "Save and reuse custom filter presets for documents and other list views."
    },
    {
      "name": "Payment Services",
      "description": "Configure and manage the payment service integration used to collect payments for your invoices."
    },
    {
      "name": "Phone Calling Codes",
      "description": "List all phone country calling codes."
    },
    {
      "name": "Reports",
      "description": "Reporting endpoints — currently covers the balance-per-client report, its summary, and XLSX export."
    },
    {
      "name": "SAF-T",
      "description": "Generate the SAF-T (Standard Audit File for Tax) export for your account."
    },
    {
      "name": "Tax Countries",
      "description": "List all tax countries."
    },
    {
      "name": "Digital signatures",
      "description": "Allows opt-in for available digital signature providers, manage its credentials, and sign invoices."
    },
    {
      "name": "EDI",
      "description": "Manage electronic invoice (CIUS-PT) generation and its additional customs/delivery fields. Note these endpoints are served under `/api/v1/edi/` on the v3 host, and address documents by a bare `id` with no document-type segment."
    },
    {
      "name": "Social Security",
      "description": "Helps self-employed accounts (trabalhadores independentes and ENI) fill in\nthe quarterly income declaration for Segurança Social. InvoiceXpress\ncalculates the quarter's totals from your invoices and an estimate of the\nmonthly contribution; you record what you reported.\n\n**This feature submits nothing to Segurança Social.** You type the figures\ninto Segurança Social Direta yourself. It only calculates and records.\n\nAuthentication is `api_key` only, and every endpoint is JSON only. The\ndeclaration endpoints are served under `/services/v1/social_security/...`\nand the settings and report endpoints under `/api/v3/accounts/...`, all on\nthe v3 host.\n\n### Typical flow\n\n1. Save your settings with a NISS (`POST /api/v3/accounts/social_security`).\n   Declarations answer `422` until they exist.\n2. Read the quarter to declare (`quarterly_declaration`), or the history\n   (`quarterly_declarations`).\n3. Report the quarter in Segurança Social Direta, then record it with a\n   self-report (`POST /api/v3/accounts/social_security_reports`).\n\n### How the numbers are calculated\n\n- **What is counted.** `Invoice`, `SimplifiedInvoice` and `InvoiceReceipt`\n  documents (and legacy documents with no type) with status `sent`,\n  `settled` or `second_copy`, dated in the month. Credit and debit notes,\n  plain receipts, drafts, cancelled and deleted documents, estimates and\n  guides are not counted.\n- **Amount.** The amount before VAT (`total_before_taxes`).\n- **Services and goods.** Each line goes into one bucket by its `unit`.\n  `unit`, `product` and `article` are goods; any other unit is a service.\n- **Estimated relevant income.** Services x 70% plus goods x 20%.\n- **Estimated monthly payment.** One third of the quarter's relevant income\n  (the monthly base), capped at 12 x IAS, multiplied by the rate:\n  21.4% for `independente`, 25.2% for `eni`. The result is never below\n  EUR 20 per month, a flat amount. One declaration covers three equal\n  monthly contributions, so the figure is per month, not per quarter.\n- **IAS.** The cap uses the IAS of the contribution year, which is the\n  quarter's year, except Q4, which uses the next year (Q4 is declared in\n  January). If that year is missing from the table (a future year, or before\n  2014), the latest known IAS is used (2026, EUR 537.13).\n\n| Year | IAS (EUR) | Cap, 12 x IAS (EUR) |\n|---|---|---|\n| 2014 to 2016 | 419.22 | 5 030.64 |\n| 2017 | 421.32 | 5 055.84 |\n| 2018 | 428.90 | 5 146.80 |\n| 2019 | 435.76 | 5 229.12 |\n| 2020 and 2021 | 438.81 | 5 265.72 |\n| 2022 | 443.20 | 5 318.40 |\n| 2023 | 480.43 | 5 765.16 |\n| 2024 | 509.26 | 6 111.12 |\n| 2025 | 522.50 | 6 270.00 |\n| 2026 | 537.13 | 6 445.56 |\n\n### Freshness\n\nThe current open month is always calculated live. A closed month with\nat least one counted document is calculated on first request and then\ncached; a closed month with none is calculated again on every request,\nunless a self-report stamped it with `submitted_at`, which stores it.\nIt is recalculated in the\nbackground when a document dated in it is finalised, cancelled or deleted,\nso the previous total can be served meanwhile. Recalculation is queued at\nmost once per month every 30 seconds: a change made inside that window is\nnot queued, and the cached total can stay out of date until a later change\nin that month.\n\n### Limitations\n\n- Every `estimated_*` field is an estimate. `total_amount` is the figure to\n  declare, but it is not yet authoritative: whether income is recognised on\n  the issue or payment date, whether credit notes net against it, and\n  whether invoices without a linked payment count are still open questions.\n- The services and goods split is a heuristic on the line `unit`, not a\n  fiscal classification.\n- `regime`, `exempt` and `special_profile` are stored and returned, but no\n  calculation uses them. There is no eligibility check: any account can\n  save a NISS, including accounts that are exempt from this declaration.\n- A self-report has no `DELETE` of its own; `DELETE\n  /api/v3/accounts/social_security` deletes all of them.\n- Error messages follow the language of the account, not the\n  `Accept-Language` header.\n"
    },
    {
      "name": "Changelog",
      "x-traitTag": true,
      "description": "Changes to the documented contract of the InvoiceXpress API v3: endpoints, fields, enum values,\nstatus codes and behaviour you can observe as an integrator. The newest version is at the top.\n\nThe version number is the one shown at the top of this reference, and it follows these rules:\n\n- **Minor** (`3.1.0`): something was added, such as a new endpoint, field or enum value. Existing\n  integrations keep working.\n- **Patch** (`3.0.1`): the documentation was corrected and now describes what the API already did.\n  No behaviour changed.\n- The major version stays at `3`. A change that would break existing integrations is released as a\n  new API version, not as `4.0.0` of this one.\n\n## 3.1.0 — 2026-11-06\n\n### Added\n\n- Archive clients: `PUT /api/v3/clients/{id}/archive` and `PUT /api/v3/clients/{id}/unarchive`.\n- `GET /api/v3/clients`: `status` filter (`all`, `active`, `archived`), and `archived_at` on each row.\n- Clients returned by show, create, update, archive and unarchive carry `can_be_deleted`,\n  `archived` and `archived_at`.\n- Archive séries: `PUT /api/v3/sequences/archive` and `PUT /api/v3/sequences/unarchive`.\n- `GET /api/v3/sequences`: `archived` filter, `archived` on each série, and `totals.total`.\n- `reference` on each row of the invoice, estimate and guide listings.\n- `PUT /api/v3/accounts/document_customization`: `logo_error` in the `200` response when the logo\n  could not be stored while the other fields were saved.\n\n### Changed\n\n- `PUT /api/v3/sequences/default` answers `422` for an archived série.\n- `PUT /api/v3/accounts/document_customization`: a logo the server cannot decode now answers\n  `422`, like any other invalid logo; it used to answer `500`.\n\n### Fixed\n\n- `PUT /api/v3/accounts/document_customization`: the `422` for an invalid logo carries the code\n  `image_not_valid`, not a sentence, and logos are limited to 200 KB as well as 1000 × 1000 pixels.\n\n## 3.0.0 — 2026-10-30\n\nFirst public release of the API v3 reference.\n"
    }
  ],
  "security": [
    {
      "apiKeyAuth": []
    }
  ],
  "paths": {
    "/api/v3/documents/{token}": {
      "get": {
        "summary": "Get Document Details",
        "operationId": "getV3Document",
        "tags": [
          "Invoices"
        ],
        "description": "Retrieves detailed information about a specific document including client data, items, financial summary, and account information. Public endpoint — no API key needed; the document token itself grants access. The response language follows the client's (or the account's) language.",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTokenParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DocumentResponse"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/documents/abc123token\""
          }
        ]
      }
    },
    "/api/v3/documents/{token}/pdf": {
      "get": {
        "summary": "Get Document PDF by Token",
        "operationId": "getV3DocumentPdfByToken",
        "tags": [
          "Invoices"
        ],
        "description": "Returns the PDF URL of the document identified by its public token, or indicates that PDF generation is in progress (poll again). Public endpoint — no API key needed; the document token itself grants access. Works for any document type.",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTokenParam"
          },
          {
            "$ref": "#/components/parameters/V3PdfAttachmentQueryParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PdfReadyResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED — the PDF is being generated (`PDF file is being generated`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PdfProcessingResponse"
                }
              }
            }
          },
          "404": {
            "description": "No document with this token (`Document not found.`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Document not found."
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "The PDF could not be generated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PdfGenerationError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/documents/abc123token/pdf\""
          }
        ]
      }
    },
    "/api/v3/documents/{document_id}/partial_payments.json": {
      "post": {
        "summary": "Create partial payment for document",
        "operationId": "createV3DocumentPartialPayment",
        "tags": [
          "Invoices",
          "Guides",
          "Estimates"
        ],
        "description": "Creates a partial payment for a document. This generates a treasury movement and client current account entry.\nUse the document numeric id (the same id returned for invoice-type and guide-type resources).\nThe `.json` suffix requests a JSON response body.\n\nSend an `Idempotency-Key` header to make retries safe: a repeated request with the same key and payload\nreplays the first answer (kept for 24 hours) instead of registering the payment twice.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentIdPathParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "example": "6f1c2a4e-1b7d-4c55-9a0e-3f2b8d7c9e10"
            },
            "description": "Optional client-generated unique key (e.g. a UUID), scoped to the account and the document. Without it, every request registers a new payment."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3PartialPaymentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Partial payment created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PartialPaymentCreatedResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED. The server sends `Content-Type: application/json` but the body is a bare plain-text string, not JSON — e.g. `Authentication Error`. Do not attempt to parse it as JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string",
                  "example": "Authentication Error"
                }
              }
            }
          },
          "404": {
            "description": "Document not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PartialPayment404Error"
                }
              }
            }
          },
          "408": {
            "description": "Request timeout - could not complete request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string",
                  "example": "Couldn't complete request"
                }
              }
            }
          },
          "409": {
            "description": "CONFLICT — a request with the same `Idempotency-Key` is still running. The body is a bare array of `{error}` objects.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "error": {
                        "type": "string"
                      }
                    }
                  }
                },
                "example": [
                  {
                    "error": "A request with this Idempotency-Key is still being processed. Wait for it to finish before retrying."
                  }
                ]
              }
            }
          },
          "422": {
            "description": "Unprocessable content. Usually validation errors as an array of `[field, message]`\ntuples, not the usual errors-array-of-objects shape used elsewhere in this API.\nOther bodies on this status:\n- a bare JSON string `The note is too long (maximum 255 characters). Please shorten it and try again.`\n  when a value is too long for a 255-character column;\n- `[{\"error\": \"This request was already sent with a different payload. Use a new Idempotency-Key for a new payment.\"}]`\n  when an `Idempotency-Key` is reused with a different payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PartialPaymentValidationError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/documents/541674/partial_payments.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/invoices": {
      "get": {
        "summary": "List Invoices",
        "operationId": "listV3Invoices",
        "tags": [
          "Invoices"
        ],
        "description": "Returns a list of all your invoices.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "$ref": "#/components/parameters/V3InvoicesQueryParamObject"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3InvoiceListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/invoices?api_key=YOUR_API_KEY&date[from]=01/01/2024&date[to]=31/12/2024&due_date[from]=01/01/2024&due_date[to]=31/12/2024&total_before_taxes[from]=0&total_before_taxes[to]=1000&total_with_taxes[from]=0&total_with_taxes[to]=1000\""
          }
        ]
      }
    },
    "/api/v3/{invoices-type}": {
      "post": {
        "summary": "Create Invoice-type Document",
        "operationId": "createV3Invoice",
        "tags": [
          "Invoices"
        ],
        "description": "Creates a new document of the specified invoice type, as a draft unless\nfinalized later through change-state. The request body wrapper key must\nbe the singular of the path segment:\n- `invoice` for `invoices`\n- `invoice_receipt` for `invoice_receipts`\n- `simplified_invoice` for `simplified_invoices`\n- `credit_note` for `credit_notes`\n- `debit_note` for `debit_notes`\n\nAny other key returns 422 `No <element> element provided`.\nThe response wrapper key follows the same rule.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeInvoiceParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateInvoiceRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3InvoiceResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed — e.g. missing `invoice` wrapper (\"No invoice element provided\"), missing items (\"No items element provided\"), the plan's document limit reached (\"Document creation limit reached for the period from ... to ...\"), or a model validation message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CreateDocumentError"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error (`Something went terribly wrong.`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/invoices?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/invoices/batches": {
      "get": {
        "summary": "List document batches for the account",
        "operationId": "getV3InvoiceBatches",
        "tags": [
          "Invoices"
        ],
        "description": "Returns all document batches belonging to the authenticated account. Each item includes the stored number_of_documents value as count (set when the import batch is finalized). Use each batch id as the batch_id query parameter on GET /api/v3/invoices to list only invoices from that batch.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DocumentBatchesResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/invoices/batches?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/invoices/{id}/check_finalize": {
      "get": {
        "summary": "Check Finalize Conditions",
        "operationId": "checkFinalizeInvoice",
        "tags": [
          "Invoices"
        ],
        "description": "Checks if there are conditions to finalize an invoice (e.g., future dates or earlier drafts).",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CheckFinalizeResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/check_finalize?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/update_summary": {
      "post": {
        "summary": "Update Invoice Summary",
        "operationId": "updateV3InvoiceSummary",
        "tags": [
          "Invoices"
        ],
        "description": "Calculates and returns the financial summary (totals, taxes, discounts, retention) for an invoice based on the provided invoice data without saving the invoice. The request body wrapper key must be the singular of the path type (invoice, invoice_receipt, simplified_invoice, credit_note, debit_note, receipt); any other key returns 422 \"No invoice element provided\" (with the expected key name).",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateSummaryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UpdateSummaryResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UpdateInvoiceSummaryError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/invoices/update_summary?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/calculate_summary": {
      "post": {
        "summary": "Calculate Invoice Summary",
        "operationId": "calculateV3InvoiceSummary",
        "tags": [
          "Invoices"
        ],
        "description": "Unvalidated counterpart of update_summary: calculates the totals from\nthe items, `retention`, `global_discount`, `currency_code`, `rate` and\ntax exemption in the body, without saving anything. Nothing else\n(client, dates, series) is read, and invalid input is coerced rather\nthan rejected, so a missing or wrong wrapper key returns a summary of\nzeros instead of an error. At most 1000 items are taken into account.\n\nThe wrapper key is the singular of the path segment (`invoice`,\n`invoice_receipt`, `simplified_invoice`, `credit_note`, `debit_note`,\n`receipt`).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateSummaryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UpdateSummaryResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error (`Something went terribly wrong.`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/invoices/calculate_summary?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"invoice\":{\"items\":[{\"name\":\"p1\",\"unit_price\":10,\"quantity\":2,\"tax\":{\"name\":\"IVA23\",\"value\":23}}]}}'"
          }
        ]
      }
    },
    "/api/v3/invoices/summary": {
      "post": {
        "summary": "Get Invoices Summary",
        "operationId": "getV3InvoicesSummary",
        "tags": [
          "Invoices"
        ],
        "description": "Returns the totals of the documents matching the filters. Accepts the same\nfilters as `GET /api/v3/invoices` (see `V3InvoicesQueryParams`: `id[]`, `except_id[]`,\n`type[]`, `status[]`, `client_id[]`, `serie_name[]`, `date`, `due_date`, `total_before_taxes`,\n`total_with_taxes`, `text`, `archived`, `non_archived`, `reference`, ...), sent either in the\nquery string or in the JSON body. Pagination does not apply: `totals.pages` is always `1`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "$ref": "#/components/parameters/V3InvoicesQueryParamObject"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3InvoiceSummaryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3InvoiceSummaryResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/invoices/summary?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/invoices/{id}/transform_document": {
      "get": {
        "summary": "Transform Document",
        "operationId": "transformV3Document",
        "tags": [
          "Invoices"
        ],
        "description": "Returns a transformed version of the specified invoice document. This is typically used to prepare the document to be converted into another invoice-type document (e.g., credit note or other variations), mirroring the data structure of a cloned document ready for further edits.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3TransformDocumentError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/transform_document?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/{id}": {
      "get": {
        "summary": "Get Document by ID",
        "operationId": "getV3DocumentById",
        "tags": [
          "Invoices"
        ],
        "description": "Retrieves detailed information about a specific document including client data, items, financial summary, and account information.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "put": {
        "summary": "Update Invoice-type Document",
        "operationId": "updateV3Invoice",
        "tags": [
          "Invoices"
        ],
        "description": "Updates a document of the specified invoice type and returns it. The\n`id` must belong to a document of that type. The request body wrapper\nkey must be the singular of the path segment (`invoice`,\n`invoice_receipt`, `simplified_invoice`, `credit_note`, `debit_note`).\nThe body accepts the same fields as create, and `items` must again\ncontain at least one item: the item list sent replaces the stored one.\n\nDocuments in status sent, settled, deleted, canceled, accepted, refused\nor second_copy cannot be changed (422 \"Document has been finalized so\ncan't be changed anymore\").\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeInvoiceParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateInvoiceRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3InvoiceResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "No document of this type with this id (`Document not found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "409": {
            "description": "The document is being saved by another request at the same time (`This document is being saved by another request. Please try again.`). Safe to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CreateDocumentError"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed — e.g. missing wrapper (\"No invoice element provided\"), missing items (\"No items element provided\"), the document is no longer editable (\"Document has been finalized so can't be changed anymore\"), or a model validation message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CreateDocumentError"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error (`Something went terribly wrong.`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"invoice\":{\"date\":\"2026-07-27\",\"due_date\":\"2026-08-27\",\"client\":{\"id\":456},\"items\":[{\"name\":\"Product Name\",\"unit_price\":100,\"quantity\":1}]}}'"
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/new": {
      "get": {
        "summary": "Get New Document Defaults",
        "operationId": "newV3Invoice",
        "tags": [
          "Invoices"
        ],
        "description": "Returns the defaults and choice lists used to build a new document of the specified invoice type (payment terms, exemption reasons, series of that type, currencies, retention options, taxes and default remarks). Nothing is created.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeInvoiceParam"
          },
          {
            "name": "client_id",
            "in": "query",
            "required": false,
            "description": "Id of a client of the account. Its payment days, exemption code, currency and observations are used for the defaults, and its basic data is returned in `client`.",
            "schema": {
              "type": "integer",
              "example": 196600840
            }
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NewDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "The defaults could not be built (the error message is returned).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CreateDocumentError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/invoices/new?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/{id}/clone": {
      "get": {
        "summary": "Clone Document",
        "operationId": "cloneV3Invoice",
        "tags": [
          "Invoices"
        ],
        "description": "Returns an unsaved copy of the document, ready to be edited and sent to\ncreate. Nothing is created: `id` and `token` are null. The copy is a\ndraft of the path type, dated today, with the due date moved by the\nclient's (or account's) payment days, the exchange rate refreshed for\nforeign-currency documents, and the account's default series of that\ntype.\n\nThe source `id` can be any document of the account; it is not checked\nagainst the path type.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeInvoiceParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "name": "keep_owner_sequence",
            "in": "query",
            "required": false,
            "description": "Only honoured on `invoices`. When `true`, the copy keeps the source document's series instead of the account default.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "No document with this id in the account (`Document not found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "The copy could not be built (the error message is returned).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CreateDocumentError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/clone?keep_owner_sequence=true&api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/invoices/{id}/handle_integration": {
      "post": {
        "summary": "Sync Invoice with an Integration",
        "operationId": "handleV3InvoiceIntegration",
        "tags": [
          "Invoices"
        ],
        "description": "Queues a background job that associates the document with an integration (plugin). Answers `{}` immediately; the result is not reported back.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "name": "plugin_id",
            "in": "query",
            "required": true,
            "description": "UUID of the plugin (integration). Can also be sent in the JSON body. An empty value uses the default plugin. Omitting the parameter entirely fails with 500.",
            "schema": {
              "type": "string",
              "example": "3f2504e0-4f89-11d3-9a0c-0305e82c3301"
            }
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Job queued.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {}
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "Missing `plugin_id`, or another unexpected error (`Something went terribly wrong.`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/handle_integration?plugin_id=3f2504e0-4f89-11d3-9a0c-0305e82c3301&api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/{id}/archive": {
      "put": {
        "summary": "Archive a document",
        "operationId": "archiveV3Document",
        "tags": [
          "Invoices"
        ],
        "description": "Archives the specified document by setting its archived flag to true and returns the updated document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "The document is still a draft — drafts cannot be archived (`Can't archive draft document`), or the update failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ArchiveDraftError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/archive?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "patch": {
        "summary": "Archive a document",
        "operationId": "archiveV3DocumentPatch",
        "tags": [
          "Invoices"
        ],
        "description": "Archives the specified document by setting its archived flag to true and returns the updated document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "The document is still a draft — drafts cannot be archived (`Can't archive draft document`), or the update failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ArchiveDraftError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PATCH \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/archive?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/{id}/comments": {
      "post": {
        "summary": "Creates a comment for a document",
        "operationId": "createV3DocumentComment",
        "tags": [
          "Invoices"
        ],
        "description": "Creates a new comment for the specified document. Comments can only be deleted within 15 minutes of creation.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateCommentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CommentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CreateCommentError"
                }
              }
            }
          },
          "500": {
            "description": "Missing `comment` wrapper (or another unexpected error): `Something went terribly wrong.`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/comments?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/{id}/comments/{comment_id}": {
      "delete": {
        "summary": "Deletes a comment from a document",
        "operationId": "deleteV3DocumentComment",
        "tags": [
          "Invoices"
        ],
        "description": "Deletes a comment from the specified document. Comments can only be deleted within 15 minutes of creation and only by the author.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/V3CommentIdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "204": {
            "description": "SUCCESS"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DeleteCommentError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/comments/1?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/{id}/movements": {
      "get": {
        "summary": "List document movements",
        "operationId": "listV3DocumentMovements",
        "tags": [
          "Invoices"
        ],
        "description": "Returns the list of movements related to the specified document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3MovementsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/movements?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/{id}/change-state.json": {
      "put": {
        "summary": "Change document state",
        "operationId": "changeV3InvoiceDocumentState",
        "tags": [
          "Invoices"
        ],
        "description": "Changes the state of an invoice-type document (`invoices-type` path segment).\n\n| From | To | Value in request body | Notes |\n| :--- | :--- | :--- | :--- |\n| draft | final | **finalized** | All types. |\n| draft | settled | **finalized** | Only `invoice_receipts`. |\n| draft | deleted | **deleted** | All types. |\n| final | canceled | **canceled** | All types. |\n| settled | canceled | **canceled** | Only `invoice_receipts`. |\n| final | settled | **settled** | All types except `invoice_receipts` and `receipts`. |\n| settled | final | **unsettled** | Only `credit_notes` and `debit_notes`. |\n\nOn `receipts` (payment receipts) the only transition is **canceled**;\ncanceling a receipt that is already canceled succeeds without change.\n\nThe request body wrapper key must be the singular of the path type\n(`invoice`, `invoice_receipt`, `simplified_invoice`, `credit_note`,\n`debit_note`, `receipt`); any other key returns 422 \"Invalid root element, expected\ninvoice\" (with the expected key name).\n\nTo cancel, send the reason in `message` inside the wrapper, e.g.\n`{\"invoice\": {\"state\": \"canceled\", \"message\": \"Document issued by mistake\"}}`.\nWithout it the API returns 422 \"The cancellation reason is a required field\".\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3ChangeInvoiceStateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ChangeInvoiceStateResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ChangeDocumentStateError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/change-state.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/{id}/pdf": {
      "get": {
        "summary": "Download document PDF",
        "operationId": "getV3DocumentPdf",
        "tags": [
          "Invoices"
        ],
        "description": "Returns the PDF URL for the specified document or indicates if PDF generation is in progress.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PdfReadyResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PdfProcessingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PdfGenerationError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/pdf?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/{id}/qr_code": {
      "get": {
        "summary": "Get QR Code",
        "operationId": "getV3DocumentQrCode",
        "tags": [
          "Invoices"
        ],
        "description": "Returns the QR Code URL for the specified document or indicates if QR Code generation is in progress.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3QrCodeReadyResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3QrCodeProcessingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "The document is still a draft — drafts have no QR Code (`QR code is not available for draft documents.`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3QrCodeDraftError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/qr_code?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/{id}/send": {
      "get": {
        "summary": "Get send document configuration",
        "operationId": "getV3DocumentSendConfig",
        "tags": [
          "Invoices"
        ],
        "description": "Returns the pre-filled email data for sending a document to a client. This includes the default recipient, subject, and body with placeholders resolved based on the document and client context.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendDocumentConfigResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendConfigError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/send?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Send document by email",
        "operationId": "sendV3Document",
        "tags": [
          "Invoices"
        ],
        "description": "Sends the specified document by email to the client.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3SendDocumentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendDocumentActionResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN — email send limit reached. Accounts that are not yet verified (Portuguese accounts without a registered series, or using the demo series) can only send a small number of emails; past that limit the account is queued for verification and this error is returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "One or more email addresses are invalid (`<address> is an invalid email`), or a trial account tried to send to an address other than the user's own (`Trial accounts can only send emails to their own address (<address> is not allowed)`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendDocumentError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/send?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"send\":{\"to\":\"client@example.com\",\"subject\":\"Your document\",\"body\":\"Please find it attached.\"}}'"
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/{id}/related_documents": {
      "get": {
        "summary": "List related documents",
        "operationId": "listV3RelatedDocuments",
        "tags": [
          "Invoices"
        ],
        "description": "Returns the list of documents related to the specified document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3RelatedDocumentsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/related_documents?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/{id}/timeline": {
      "get": {
        "summary": "Returns timeline activities for a specific document",
        "operationId": "getV3DocumentTimeline",
        "tags": [
          "Invoices"
        ],
        "description": "Retrieves timeline activities for a specific document including status changes, comments, and other events.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3TimelineResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/timeline?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{invoices-type}/{id}/unarchive": {
      "put": {
        "summary": "Unarchive a document",
        "operationId": "unarchiveV3Document",
        "tags": [
          "Invoices"
        ],
        "description": "Unarchives the specified document by setting its archived flag to false and returns the updated document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "The document is still a draft — drafts cannot be unarchived (`Can't unarchive draft document`), or the update failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ArchiveDraftError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Can't unarchive draft document"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/unarchive?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "patch": {
        "summary": "Unarchive a document",
        "operationId": "unarchiveV3DocumentPatch",
        "tags": [
          "Invoices"
        ],
        "description": "Unarchives the specified document by setting its archived flag to false and returns the updated document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeInvoiceOrReceiptParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "The document is still a draft — drafts cannot be unarchived (`Can't unarchive draft document`), or the update failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ArchiveDraftError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Can't unarchive draft document"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PATCH \"https://api-v3.app.invoicexpress.com/api/v3/invoices/541674/unarchive?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/guides": {
      "get": {
        "summary": "List Guides",
        "operationId": "listV3Guides",
        "tags": [
          "Guides"
        ],
        "description": "Returns a list of all your guides.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "$ref": "#/components/parameters/V3GuidesQueryParamObject"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/guides?api_key=YOUR_API_KEY&date[from]=2026-04-27&date[to]=2026-04-27&loaded_at[from]=2026-04-27&loaded_at[to]=2026-04-27&total_before_taxes[from]=0&total_before_taxes[to]=1000&total_with_taxes[from]=0&total_with_taxes[to]=1000\""
          }
        ]
      },
      "post": {
        "summary": "List Guides (POST)",
        "operationId": "listV3GuidesPost",
        "tags": [
          "Guides"
        ],
        "description": "Same as `GET /api/v3/guides`, with the filters and pagination options sent in a JSON body instead of the query string. Useful when the filters (for example long `id` or `client_id` lists) do not fit in a URL. Returns the same response.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3GuidesQueryParams"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "503": {
            "description": "SERVICE UNAVAILABLE - the document search timed out (\"Document search is temporarily unavailable. Please try again shortly.\"). Retry after the number of seconds in the `Retry-After` header (30).",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "example": 30
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/guides?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"page\":1,\"items_per_page\":10,\"status\":[\"sent\"]}'"
          }
        ]
      }
    },
    "/api/v3/guides/summary": {
      "post": {
        "summary": "Get Guides Summary",
        "operationId": "getV3GuidesSummary",
        "tags": [
          "Guides"
        ],
        "description": "Returns the totals of the specific documents select",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3GuideSummaryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideSummaryResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED The API Key parameter is missing or is incorrectly entered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/guides/summary?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/{guides-type}": {
      "post": {
        "summary": "Create Guide",
        "operationId": "createV3Guide",
        "tags": [
          "Guides"
        ],
        "description": "Creates a new guide of the specified type, as a draft. The request body wrapper key must match the path segment:\n- `shipping` for `shippings`\n- `transport` for `transports`\n- `devolution` for `devolutions`\n\n`loaded_at` and at least one item are required. Portuguese accounts must also send `address_from` and `address_to`, each with `detail`, `city`, `postal_code` and `country`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateGuideRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "CREATED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. Messages include:\n- \"No transport element provided\" (wrapper missing; the element name follows the path)\n- \"No items element provided\"\n- \"No address_from element provided\" / \"No address_to element provided\" (Portuguese accounts)\n- `Load date must be on or after <current date and time>`\n- \"No client was found with the id provided.\"\n- `Document creation limit reached for the period from <start> to <end>.`\n- model validation messages\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideWriteError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/transports?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"transport\":{\"date\":\"2026-07-13\",\"loaded_at\":\"2026-07-13 13:07:00\",\"address_from\":{\"detail\":\"123 Loading Street\",\"city\":\"Lisbon\",\"postal_code\":\"1000-001\",\"country\":\"Portugal\"},\"address_to\":{\"detail\":\"456 Client Street\",\"city\":\"Porto\",\"postal_code\":\"4000-001\",\"country\":\"Portugal\"},\"client\":{\"name\":\"John Doe\"},\"items\":[{\"name\":\"Product Name\",\"unit_price\":100,\"quantity\":1,\"tax\":{\"name\":\"IVA23\"}}]}}'"
          }
        ]
      }
    },
    "/api/v3/{guides-type}/new": {
      "get": {
        "summary": "Get New Guide Defaults",
        "operationId": "getV3NewGuide",
        "tags": [
          "Guides"
        ],
        "description": "Returns the defaults and choices used to fill in a new guide of the specified type (sequences, currencies, taxes, exemption reasons, due date and retention choices, address countries). Nothing is created.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "client_id",
            "in": "query",
            "required": false,
            "description": "Id of a client of the account. When sent, the client's defaults (payment days, exemption code, currency, observations) are pre-selected and a `client` summary is included.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "Language of the labels (`pt`, `en`, `es`). Defaults to the account's language.",
            "schema": {
              "type": "string",
              "enum": [
                "pt",
                "en",
                "es"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NewGuideResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "The defaults could not be built (the error message is returned).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/transports/new?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{guides-type}/calculate_summary": {
      "post": {
        "summary": "Calculate Guide Summary",
        "operationId": "calculateV3GuideSummary",
        "tags": [
          "Guides"
        ],
        "description": "Calculates the financial summary of a guide from its items, retention, global discount, currency and tax exemption, without saving anything. Unlike `update_summary`, the input is not validated — invalid values are coerced and a missing wrapper gives an all-zero summary — so it always answers 200 unless an unexpected error occurs.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateSummaryGuideRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UpdateGuideSummaryResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/transports/calculate_summary?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"transport\":{\"items\":[{\"name\":\"p1\",\"unit_price\":10,\"quantity\":2,\"tax\":{\"name\":\"IVA23\",\"value\":23}}]}}'"
          }
        ]
      }
    },
    "/api/v3/{guides-type}/update_summary": {
      "post": {
        "summary": "Update Guide Summary",
        "operationId": "updateV3GuideSummary",
        "tags": [
          "Guides"
        ],
        "description": "Calculates and returns the financial summary (totals, taxes, discounts, retention) for an guide based on the provided guide data without saving the guide. This endpoint is useful for previewing calculations before creating or updating an guide.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateSummaryGuideRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UpdateGuideSummaryResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UpdateInvoiceSummaryError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/transports/update_summary?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/{guides-type}/{id}": {
      "get": {
        "summary": "Get Guide by ID",
        "operationId": "getV3GuideById",
        "tags": [
          "Guides"
        ],
        "description": "Retrieves detailed information about a specific document including client data, items, financial summary, and account information",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Document details retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED - Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - An unexpected error occurred",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/transports/541674?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "put": {
        "summary": "Update Guide",
        "operationId": "updateV3Guide",
        "tags": [
          "Guides"
        ],
        "description": "Updates a guide of the specified type. The wrapper key must match the path segment (`shipping`, `transport` or `devolution`).\n\nThe same rules as on create apply: `loaded_at` (not in the past) and at least one item are required, and Portuguese accounts must send complete `address_from` and `address_to`. The item list replaces the existing items. Guides that are sent, settled, deleted, canceled or second copies can no longer be edited.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateGuideRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - \"Document not found\" (no guide of this type with that id on the account)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "409": {
            "description": "CONFLICT - \"This document is being saved by another request. Please try again.\" Safe to retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideWriteError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. Messages include:\n- \"Document has been finalized so can't be changed anymore\"\n- \"No transport element provided\" (the element name follows the path)\n- \"No items element provided\"\n- \"No address_from element provided\" / \"No address_to element provided\" (Portuguese accounts)\n- `Load date must be on or after <current date and time>`\n- model validation messages\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideWriteError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/transports/263315060?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"transport\":{\"loaded_at\":\"2026-07-13 13:07:00\",\"address_from\":{\"detail\":\"123 Loading Street\",\"city\":\"Lisbon\",\"postal_code\":\"1000-001\",\"country\":\"Portugal\"},\"address_to\":{\"detail\":\"456 Client Street\",\"city\":\"Porto\",\"postal_code\":\"4000-001\",\"country\":\"Portugal\"},\"items\":[{\"name\":\"Product Name\",\"unit_price\":100,\"quantity\":1,\"tax\":{\"name\":\"IVA23\"}}]}}'"
          }
        ]
      }
    },
    "/api/v3/{guides-type}/{id}/clone": {
      "get": {
        "summary": "Clone Guide",
        "operationId": "cloneV3Guide",
        "tags": [
          "Guides"
        ],
        "description": "Returns a new, unsaved draft guide of the specified type pre-filled from an existing document — nothing is created. The clone gets today's date, `loaded_at` 5 minutes from now, the account's default sequence for the type and, for Portuguese accounts, copies of the source addresses. Submit it with `POST /api/v3/{guides-type}` to create it. Unsaved fields such as `id` are null.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - \"Document not found\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY - the document could not be cloned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideWriteError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/transports/263315060/clone?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{guides-type}/{id}/movements": {
      "get": {
        "summary": "List guide movements",
        "operationId": "listV3GuideMovements",
        "tags": [
          "Guides"
        ],
        "description": "Returns the payment and reimbursement movements of the specified guide and its related documents. Usually empty for guides.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3MovementsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - \"Document not found\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/transports/263315060/movements?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{guides-type}/{id}/archive": {
      "put": {
        "summary": "Archive a guide document",
        "operationId": "archiveV3GuideDocument",
        "tags": [
          "Guides"
        ],
        "description": "Archives the specified guide document by setting its archived flag to true and returns the updated document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Guide archived successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED - Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "The document is still a draft — drafts cannot be archived (`Can't archive draft document`), or the update failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ArchiveDraftError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - An unexpected error occurred",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/transports/541674/archive?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "patch": {
        "summary": "Archive a guide document",
        "operationId": "archiveV3GuideDocumentPatch",
        "tags": [
          "Guides"
        ],
        "description": "Archives the specified guide document by setting its archived flag to true and returns the updated document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Guide archived successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED - Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "The document is still a draft — drafts cannot be archived (`Can't archive draft document`), or the update failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ArchiveDraftError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - An unexpected error occurred",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PATCH \"https://api-v3.app.invoicexpress.com/api/v3/transports/541674/archive?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{guides-type}/{id}/comments": {
      "post": {
        "summary": "Creates a comment for a document",
        "operationId": "createV3GuideDocumentComment",
        "tags": [
          "Guides"
        ],
        "description": "Creates a new comment for the specified document. Comments can only be deleted within 15 minutes of creation.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateCommentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CommentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED - Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CreateCommentError"
                }
              }
            }
          },
          "500": {
            "description": "Missing `comment` wrapper (or another unexpected error): `Something went terribly wrong.`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/transports/541674/comments?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/{guides-type}/{id}/comments/{comment_id}": {
      "delete": {
        "summary": "Deletes a comment from a document",
        "operationId": "deleteV3GuideDocumentComment",
        "tags": [
          "Guides"
        ],
        "description": "Deletes a comment from the specified document. Comments can only be deleted within 15 minutes of creation and only by the author.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/V3CommentIdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "204": {
            "description": "SUCCESS - Comment deleted"
          },
          "401": {
            "description": "ACCESS DENIED - Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN - Comment cannot be deleted (time expired or not authorized)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DeleteCommentError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/transports/541674/comments/1?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{guides-type}/{id}/change-state.json": {
      "put": {
        "summary": "Change document state",
        "operationId": "changeV3GuideDocumentState",
        "tags": [
          "Guides"
        ],
        "description": "Changes the state of a guide-type document (`guides-type` path segment: shippings, transports, or devolutions).\n\n| From | To | Value in request body |\n| :--- | :--- | :--- |\n| draft | final | **finalized** |\n| draft | deleted | **deleted** |\n| final | canceled | **canceled** |\n\nTo cancel, send the reason in `message` inside the wrapper, e.g.\n`{\"transport\": {\"state\": \"canceled\", \"message\": \"Goods were not shipped\"}}`.\nWithout it the API returns 422 \"The cancellation reason is a required field\".\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3ChangeGuideStateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ChangeGuideStateResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ChangeDocumentStateError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/transports/541674/change-state.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/{guides-type}/{id}/pdf": {
      "get": {
        "summary": "Download guide PDF",
        "operationId": "getV3GuidePdf",
        "tags": [
          "Guides"
        ],
        "description": "Returns the PDF URL for the specified guide or indicates if PDF generation is in progress.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "PDF is ready and URL is available",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PdfReadyResponse"
                }
              }
            }
          },
          "202": {
            "description": "PDF generation is in progress",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PdfProcessingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED - Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "PDF generation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PdfGenerationError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - An unexpected error occurred",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/transports/541674/pdf?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{guides-type}/{id}/qr_code": {
      "get": {
        "summary": "Get QR Code",
        "operationId": "getV3GuideQrCode",
        "tags": [
          "Guides"
        ],
        "description": "Returns the QR Code URL for the specified document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "QR Code is ready and URL is available",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3QrCodeReadyResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED — the QR Code is still being generated; poll again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3QrCodeProcessingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED - Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — the document is still a draft, so no QR Code exists yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3QrCodeDraftError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - An unexpected error occurred",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/transports/541674/qr_code?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{guides-type}/{id}/send": {
      "get": {
        "summary": "Get send document configuration",
        "operationId": "getV3GuideSendConfig",
        "tags": [
          "Guides"
        ],
        "description": "Returns the pre-filled email data for sending a guide document to a client. This includes the default recipient, subject, and body with placeholders resolved based on the document and client context.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Send document payload successfully retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendDocumentConfigResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED - Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "Unable to retrieve send document configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendConfigError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - An unexpected error occurred",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/transports/541674/send?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Send document by email",
        "operationId": "sendV3GuideDocument",
        "tags": [
          "Guides"
        ],
        "description": "Sends the specified guide document by email to the client.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3SendDocumentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Send document payload successfully retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendDocumentActionResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED - Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN — email send limit reached. Accounts that are not yet verified (Portuguese accounts without a registered series, or using the demo series) can only send a small number of emails; past that limit the account is queued for verification and this error is returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "One or more email addresses are invalid (`<address> is an invalid email`), or a trial account tried to send to an address other than the user's own (`Trial accounts can only send emails to their own address (<address> is not allowed)`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendDocumentError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - An unexpected error occurred",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/transports/541674/send?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"send\":{\"to\":\"client@example.com\",\"subject\":\"Your document\",\"body\":\"Please find it attached.\"}}'"
          }
        ]
      }
    },
    "/api/v3/{guides-type}/{id}/related_documents": {
      "get": {
        "summary": "List related documents",
        "operationId": "listV3GuideRelatedDocuments",
        "tags": [
          "Guides"
        ],
        "description": "Returns the list of documents related to the specified guide document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Related documents retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideRelatedDocumentsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED - Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - An unexpected error occurred",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/transports/541674/related_documents?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{guides-type}/{id}/timeline": {
      "get": {
        "summary": "Returns timeline activities for a specific document",
        "operationId": "getV3GuideTimeline",
        "tags": [
          "Guides"
        ],
        "description": "Retrieves timeline activities for a specific document including status changes, comments, and other events",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Timeline activities retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideTimelineResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED - Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - An unexpected error occurred",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/transports/541674/timeline?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{guides-type}/{id}/unarchive": {
      "put": {
        "summary": "Unarchive a guide document",
        "operationId": "unarchiveV3GuideDocument",
        "tags": [
          "Guides"
        ],
        "description": "Unarchives the specified guide document by setting its archived flag to false and returns the updated document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Guide unarchived successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED - Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "The document is still a draft — drafts cannot be unarchived (`Can't unarchive draft document`), or the update failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ArchiveDraftError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Can't unarchive draft document"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - An unexpected error occurred",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/transports/541674/unarchive?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "patch": {
        "summary": "Unarchive a guide document",
        "operationId": "unarchiveV3GuideDocumentPatch",
        "tags": [
          "Guides"
        ],
        "description": "Unarchives the specified guide document by setting its archived flag to false and returns the updated document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentTypeGuideParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "Guide unarchived successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3GuideDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED - Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "The document is still a draft — drafts cannot be unarchived (`Can't unarchive draft document`), or the update failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ArchiveDraftError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Can't unarchive draft document"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - An unexpected error occurred",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PATCH \"https://api-v3.app.invoicexpress.com/api/v3/transports/541674/unarchive?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/estimates": {
      "get": {
        "summary": "List Estimates",
        "operationId": "listV3Estimates",
        "tags": [
          "Estimates"
        ],
        "description": "Returns a list of all your estimates (quotes, proformas and fees notes).",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "$ref": "#/components/parameters/V3EstimatesQueryParamObject"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/estimates?api_key=YOUR_API_KEY&date[from]=2026-04-27&date[to]=2026-04-27&valid_to[from]=2026-04-27&valid_to[to]=2026-04-27&total_before_taxes[from]=0&total_before_taxes[to]=1000&total_with_taxes[from]=0&total_with_taxes[to]=1000\""
          }
        ]
      },
      "post": {
        "summary": "List Estimates (POST)",
        "operationId": "listV3EstimatesPost",
        "tags": [
          "Estimates"
        ],
        "description": "Same as `GET /api/v3/estimates`, with the filters sent as a JSON body instead of\nthe query string (useful for long `id` / `client_id` lists). The response is identical.\nPage size defaults to 10.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3EstimateIndexRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - \"Something went terribly wrong.\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "503": {
            "description": "SERVICE UNAVAILABLE - the search backend timed out: \"Document search is temporarily unavailable. Please try again shortly.\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/estimates?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"page\":1,\"per_page\":10,\"status\":[\"draft\"],\"date\":{\"from\":\"2026-04-01\",\"to\":\"2026-04-30\"}}'"
          }
        ]
      }
    },
    "/api/v3/estimates/summary": {
      "post": {
        "summary": "Get Estimates Summary",
        "operationId": "getV3EstimatesSummary",
        "tags": [
          "Estimates"
        ],
        "description": "Returns the totals of the specific documents selected.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3EstimateSummaryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateSummaryResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/estimates/summary?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/{estimate_type}": {
      "post": {
        "summary": "Create Estimate",
        "operationId": "createV3Estimate",
        "tags": [
          "Estimates"
        ],
        "description": "Creates a new estimate of the specified type. The request body wrapper key must match the path segment:\n- `quote` for `quotes`\n- `proforma` for `proformas`\n- `fees_note` for `fees_notes`\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateEstimateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "CREATED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/quotes?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"quote\":{\"date\":\"2026-05-11\",\"items\":[{\"name\":\"Product Name\",\"unit_price\":100,\"quantity\":1}]}}'"
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/update_summary": {
      "post": {
        "summary": "Update Estimate Summary",
        "operationId": "updateV3EstimateSummary",
        "tags": [
          "Estimates"
        ],
        "description": "Calculates and returns the financial summary (totals, taxes, discounts, retention) for an estimate based on the provided data without saving it. The request body wrapper key must be the singular of the path type (quote, proforma, fees_note); any other key returns 422 \"No quote element provided\" (with the expected key name).",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateSummaryEstimateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UpdateEstimateSummaryResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UpdateInvoiceSummaryError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/quotes/update_summary?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/calculate_summary": {
      "post": {
        "summary": "Calculate Estimate Summary",
        "operationId": "calculateV3EstimateSummary",
        "tags": [
          "Estimates"
        ],
        "description": "Calculates the totals (sum, discount, taxes, retention, total) for the items sent,\nwithout validating or saving anything. Unlike `update_summary`, invalid input is\ncoerced instead of rejected: a missing or wrongly named wrapper key, or no `items`,\nreturns an all-zero summary with 200. Only `items`, `retention`, `global_discount`,\n`currency_code`, `rate` and `tax_exemption` are read; at most 1000 items are processed.\nThe wrapper key is the singular of the path type (quote, proforma, fees_note).\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateSummaryEstimateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UpdateEstimateSummaryResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - \"Something went terribly wrong.\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/quotes/calculate_summary?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"quote\":{\"items\":[{\"name\":\"Service A\",\"unit_price\":100,\"quantity\":2,\"tax\":{\"name\":\"IVA23\"}}]}}'"
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/new": {
      "get": {
        "summary": "New Estimate Defaults",
        "operationId": "newV3Estimate",
        "tags": [
          "Estimates"
        ],
        "description": "Returns the defaults and choices needed to build a new estimate of the given type\n(due-date options, exemption reasons, issuable sequences, currencies, retention\noptions, default remarks, taxes). Nothing is created. When `client_id` is sent, the\nclient's payment days, exemption code, currency and observations take priority over\nthe account's.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "client_id",
            "in": "query",
            "required": false,
            "description": "Id of a client of the account, used to pre-select client-specific defaults and return a short `client` object.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateNewResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY - the defaults could not be built; the error carries the underlying message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - \"Something went terribly wrong.\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/quotes/new?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/{id}": {
      "get": {
        "summary": "Get Estimate by ID",
        "operationId": "getV3EstimateById",
        "tags": [
          "Estimates"
        ],
        "description": "Retrieves detailed information about a specific estimate document including client data, items, financial summary, and account information.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "put": {
        "summary": "Update Estimate",
        "operationId": "updateV3Estimate",
        "tags": [
          "Estimates"
        ],
        "description": "Updates an estimate of the given type. The wrapper key must be the singular of the\npath type (`quote`, `proforma`, `fees_note`). `items` is required and replaces the\nwhole item set. Documents in state sent, settled, deleted, canceled, accepted,\nrefused or second_copy cannot be edited.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateEstimateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - no document of this type with this id in the account: \"Document not found\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "409": {
            "description": "CONFLICT - the document is locked by a concurrent save; safe to retry: \"This document is being saved by another request. Please try again.\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. Messages include:\n- `No quote element provided` (wrapper missing; names the expected key)\n- `No items element provided`\n- `Document has been finalized so can't be changed anymore`\n- `No client was found with the id provided.`\n- model validation messages (e.g. `Date can't be blank`)\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - \"Something went terribly wrong.\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"quote\":{\"date\":\"2026-05-11\",\"due_date\":\"2026-06-11\",\"items\":[{\"name\":\"Service A\",\"unit_price\":100,\"quantity\":1,\"tax\":{\"name\":\"IVA23\"}}]}}'"
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/{id}/clone": {
      "get": {
        "summary": "Clone Estimate",
        "operationId": "cloneV3Estimate",
        "tags": [
          "Estimates"
        ],
        "description": "Returns an unsaved draft copy of the document, as an estimate of the path type, ready to\nbe edited and submitted with the create operation. Nothing is persisted: the returned\ndocument has no `id`. Date is today, due date is today plus the client's (else the\naccount's) payment days, and the exchange rate is refreshed for foreign-currency\ndocuments. The sequence is the account's default for the type unless\n`keep_owner_sequence=true`. The source `id` may be any document of the account (not\nonly one of the path type); the copy always takes the path type.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "keep_owner_sequence",
            "in": "query",
            "required": false,
            "description": "When true, keeps the source document's sequence (if it still belongs to the account) instead of the account's default sequence.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - \"Document not found\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY - the copy could not be built; the error carries the underlying message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - \"Something went terribly wrong.\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/clone?keep_owner_sequence=false&api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/{id}/movements": {
      "get": {
        "summary": "List estimate movements",
        "operationId": "listV3EstimateMovements",
        "tags": [
          "Estimates"
        ],
        "description": "Returns the payments and reimbursements recorded against the estimate, its related documents and their receipts (non-canceled treasury movements of the document's client).",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3MovementsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND - \"Document not found\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR - \"Something went terribly wrong.\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/movements?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/{id}/archive": {
      "put": {
        "summary": "Archive a document",
        "operationId": "archiveV3EstimateDocument",
        "tags": [
          "Estimates"
        ],
        "description": "Archives the specified estimate document by setting its archived flag to true and returns the updated document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/archive?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "patch": {
        "summary": "Archive a document",
        "operationId": "archiveV3EstimateDocumentPatch",
        "tags": [
          "Estimates"
        ],
        "description": "Archives the specified estimate document by setting its archived flag to true and returns the updated document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PATCH \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/archive?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/{id}/comments": {
      "post": {
        "summary": "Creates a comment for a document",
        "operationId": "createV3EstimateComment",
        "tags": [
          "Estimates"
        ],
        "description": "Creates a new comment for the specified estimate document. Comments can only be deleted within 15 minutes of creation.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateCommentRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CommentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CreateCommentError"
                }
              }
            }
          },
          "500": {
            "description": "Missing `comment` wrapper (or another unexpected error). The error text is the exception message, e.g. `param is missing or the value is empty or invalid: comment`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/comments?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/{id}/comments/{comment_id}": {
      "delete": {
        "summary": "Deletes a comment from a document",
        "operationId": "deleteV3EstimateComment",
        "tags": [
          "Estimates"
        ],
        "description": "Deletes a comment from the specified estimate document. Comments can only be deleted within 15 minutes of creation and only by the author.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/V3CommentIdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "204": {
            "description": "SUCCESS"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DeleteCommentError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/comments/1?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/{id}/pdf": {
      "get": {
        "summary": "Download estimate PDF",
        "operationId": "getV3EstimatePdf",
        "tags": [
          "Estimates"
        ],
        "description": "Returns the PDF URL for the specified estimate or indicates if PDF generation is in progress.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PdfReadyResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PdfProcessingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PdfGenerationError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/pdf?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/{id}/qr_code": {
      "get": {
        "summary": "Get QR Code",
        "operationId": "getV3EstimateQrCode",
        "tags": [
          "Estimates"
        ],
        "description": "Returns the QR Code URL for the specified estimate or indicates if QR Code generation is in progress.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3QrCodeReadyResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3QrCodeProcessingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — the estimate is still a draft, so no QR Code exists yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3QrCodeDraftError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/qr_code?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/{id}/send": {
      "get": {
        "summary": "Get send document configuration",
        "operationId": "getV3EstimateSendConfig",
        "tags": [
          "Estimates"
        ],
        "description": "Returns the pre-filled email data for sending an estimate to a client. This includes the default recipient, subject, and body with placeholders resolved based on the document and client context.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendDocumentConfigResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendConfigError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/send?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Send document by email",
        "operationId": "sendV3EstimateDocument",
        "tags": [
          "Estimates"
        ],
        "description": "Sends the specified estimate by email to the client.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3SendDocumentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendDocumentActionResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN — email send limit reached. Accounts that are not yet verified (Portuguese accounts without a registered series, or using the demo series) can only send a small number of emails; past that limit the account is queued for verification and this error is returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "One or more email addresses are invalid (`<address> is an invalid email`), or a trial account tried to send to an address other than the user's own (`Trial accounts can only send emails to their own address (<address> is not allowed)`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendDocumentError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/send?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"send\":{\"to\":\"client@example.com\",\"subject\":\"Your document\",\"body\":\"Please find it attached.\"}}'"
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/{id}/related_documents": {
      "get": {
        "summary": "List related documents",
        "operationId": "listV3EstimateRelatedDocuments",
        "tags": [
          "Estimates"
        ],
        "description": "Returns the list of documents related to the specified estimate document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateRelatedDocumentsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/related_documents?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/{id}/timeline": {
      "get": {
        "summary": "Returns timeline activities for a specific document",
        "operationId": "getV3EstimateTimeline",
        "tags": [
          "Estimates"
        ],
        "description": "Retrieves timeline activities for a specific estimate document including status changes, comments, and other events.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateTimelineResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/timeline?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/{id}/unarchive": {
      "put": {
        "summary": "Unarchive a document",
        "operationId": "unarchiveV3EstimateDocument",
        "tags": [
          "Estimates"
        ],
        "description": "Unarchives the specified document by setting its archived flag to false and returns the updated document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "The document is still a draft — drafts cannot be unarchived (`Can't unarchive draft document`), or the update failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ArchiveDraftError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Can't unarchive draft document"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/unarchive?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "patch": {
        "summary": "Unarchive a document",
        "operationId": "unarchiveV3EstimateDocumentPatch",
        "tags": [
          "Estimates"
        ],
        "description": "Unarchives the specified document by setting its archived flag to false and returns the updated document.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3EstimateDocumentResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "The document is still a draft — drafts cannot be unarchived (`Can't unarchive draft document`), or the update failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ArchiveDraftError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Can't unarchive draft document"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PATCH \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/unarchive?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/{estimate_type}/{id}/change-state.json": {
      "put": {
        "summary": "Change estimate state",
        "operationId": "changeV3EstimateDocumentState",
        "tags": [
          "Estimates"
        ],
        "description": "Changes the state of an estimate document (`estimate_type` path segment: quotes, proformas, fees_notes).\n\n| From | To | Value in request body |\n| :--- | :--- | :--- |\n| draft | sent | **finalized** |\n| draft | deleted | **deleted** |\n| sent, refused | accepted | **accept** |\n| sent, accepted | refused | **refuse** |\n| sent, accepted, refused | canceled | **canceled** |\n\nThe request body wrapper key must be the singular of the path type\n(`quote`, `proforma`, `fees_note`); any other key returns 422 \"Invalid\nroot element, expected quote\" (with the expected key name).\n\nTo cancel, send the reason in `message` inside the wrapper, e.g.\n`{\"quote\": {\"state\": \"canceled\", \"message\": \"Client withdrew the request\"}}`.\nWithout it the API returns 422 \"The cancellation reason is a required field\".\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3DocumentTypeEstimateParam"
          },
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3ChangeEstimateStateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ChangeEstimateStateResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ChangeDocumentStateError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/quotes/541674/change-state.json?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/sequences": {
      "get": {
        "summary": "List Sequences",
        "operationId": "listV3Sequences",
        "tags": [
          "Sequences"
        ],
        "description": "Returns a paginated list of the sequences (séries) of the current account, 10 per page by default, newest first. Archived séries are included unless `archived=false` is sent.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "example": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Number of series per page. `items_per_page` and `page_items` are accepted as aliases.",
            "schema": {
              "type": "integer",
              "default": 10,
              "example": 10
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Sort field. Any other value sorts by `created_at`.",
            "schema": {
              "type": "string",
              "enum": [
                "created_at",
                "serie_name"
              ],
              "default": "created_at",
              "example": "serie_name"
            }
          },
          {
            "name": "sort_order",
            "in": "query",
            "required": false,
            "description": "Sort direction.",
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ],
              "default": "DESC",
              "example": "ASC"
            }
          },
          {
            "name": "text",
            "in": "query",
            "required": false,
            "description": "Free-text search on the série name. Ignored when its first word has fewer than 3 characters.",
            "schema": {
              "type": "string",
              "example": "SERIE"
            }
          },
          {
            "name": "archived",
            "in": "query",
            "required": false,
            "description": "`true` returns only archived séries, `false` only séries that are not archived. Absent, or any other value, returns both.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "example": "false"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SequenceListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/sequences?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Create Sequence",
        "operationId": "createV3Sequence",
        "tags": [
          "Sequences"
        ],
        "description": "Creates a new sequence for the current account. The operation is asynchronous — poll `GET /api/v3/sequences/create_status` with the returned `status_endpoint` params to check completion.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateSequenceRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "CREATED — the série was created (`create_and_registry` not set)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SequenceAsyncResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED — the série was created and its AT registration started (`create_and_registry` set to `true`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SequenceAsyncResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — the série failed validation (invalid or already used name)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SequenceValidationError"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — the `sequence` root object is missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SequenceMissingRootError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — also returned, with code `registration_error`, when the AT registration could not be started",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/V3ServerError"
                    },
                    {
                      "$ref": "#/components/schemas/V3SequenceValidationError"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/sequences?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"sequence\":{\"serie_name\":\"SERIE2026\",\"set_as_default\":false,\"create_and_registry\":false}}'"
          }
        ]
      }
    },
    "/api/v3/sequences/by_name": {
      "get": {
        "summary": "Get Sequences By Name",
        "operationId": "getV3SequencesByName",
        "tags": [
          "Sequences"
        ],
        "description": "Returns a list of all sequence names for the account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SequencesByNameResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/sequences/by_name?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/sequences/collection": {
      "get": {
        "summary": "Get Sequence Collection",
        "operationId": "getV3SequenceCollection",
        "tags": [
          "Sequences"
        ],
        "description": "Returns the registration collection for a given sequence, showing the registration status per document category.",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "description": "The serie name to retrieve the collection for.",
            "schema": {
              "type": "string",
              "example": "INVOICEXPRESSDEMO"
            }
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SequenceCollectionResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — the required `name` query parameter is missing or empty",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SequenceNameError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — also returned when no série with the given `name` exists in the account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/sequences/collection?api_key=YOUR_API_KEY&name=INVOICEXPRESSDEMO\""
          }
        ]
      }
    },
    "/api/v3/sequences/create_status": {
      "get": {
        "summary": "Check Sequence Creation Status",
        "operationId": "getV3SequenceCreateStatus",
        "tags": [
          "Sequences"
        ],
        "description": "Checks the creation status of a sequence. Called with the query string returned in `status_endpoint` from the create and register operations. No API key is needed — the encrypted `account_id` token identifies the account. Returns `202` while the operation is still running and `200` once it has finished; a failed operation is also answered with `200` and `success` set to `false`.",
        "security": [],
        "parameters": [
          {
            "name": "account_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "7117e09c4cd4ba7b05b2cc10e34d8684"
            },
            "description": "Encrypted account token, exactly as returned in `status_endpoint`. It is not the numeric account id."
          },
          {
            "name": "serie_name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "SERIE2026"
            },
            "description": "The serie name being created/registered."
          },
          {
            "name": "create_and_registry",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "example": false
            },
            "description": "Whether the operation also registers the serie with the tax authority."
          },
          {
            "name": "sequence_already_exists",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "example": false
            },
            "description": "Whether the serie already existed before this operation."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SequenceCreateStatusResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED — operation still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SequenceCreateStatusResponse"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/sequences/create_status?account_id=7117e09c4cd4ba7b05b2cc10e34d8684&serie_name=SERIE2026&create_and_registry=false&sequence_already_exists=false\""
          }
        ]
      }
    },
    "/api/v3/sequences/default": {
      "put": {
        "summary": "Set Default Sequence",
        "operationId": "setV3DefaultSequence",
        "tags": [
          "Sequences"
        ],
        "description": "Sets the default sequence for the current account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3SetDefaultSequenceRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SuccessResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — missing required parameters, or the série is archived (\"Cannot set an archived sequence as default. Unarchive it first.\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/sequences/default?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/sequences/archive": {
      "put": {
        "summary": "Archive Sequence",
        "operationId": "archiveV3Sequence",
        "tags": [
          "Sequences"
        ],
        "description": "Archives a série, for every document type at once. An archived série is no longer\noffered when a new document is prepared, and cannot be made the default. It does not\nblock anything else: existing documents are unaffected, and a document can still be\ncreated with it through the API. The default série cannot be archived.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3ArchiveSequenceRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SuccessResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN — the user's role cannot manage séries (guides-only contributors)."
          },
          "404": {
            "description": "NOT FOUND — no série with this name in the account (\"Sequence not found\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — the `sequence` root object is missing, or the série is the default (\"Cannot archive the default sequence. Set a different default sequence before archiving.\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/sequences/archive?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"sequence\":{\"serie_name\":\"SERIE2026\"}}'"
          }
        ]
      }
    },
    "/api/v3/sequences/unarchive": {
      "put": {
        "summary": "Unarchive Sequence",
        "operationId": "unarchiveV3Sequence",
        "tags": [
          "Sequences"
        ],
        "description": "Unarchives a série, for every document type at once, so it is offered again when a\nnew document is prepared.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3ArchiveSequenceRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SuccessResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN — the user's role cannot manage séries (guides-only contributors)."
          },
          "404": {
            "description": "NOT FOUND — no série with this name in the account (\"Sequence not found\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — the `sequence` root object is missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/sequences/unarchive?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"sequence\":{\"serie_name\":\"SERIE2026\"}}'"
          }
        ]
      }
    },
    "/api/v3/sequences/register": {
      "put": {
        "summary": "Register Sequence",
        "operationId": "registerV3Sequence",
        "tags": [
          "Sequences"
        ],
        "description": "Registers a sequence with the tax authority (AT). The operation is asynchronous — poll `GET /api/v3/sequences/create_status` with the returned `status_endpoint` params to check completion.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3RegisterSequenceRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "ACCEPTED — registration started",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SequenceAsyncResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — a sequence registry failed validation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SequenceValidationError"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — the `sequence` root object is missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SequenceMissingRootError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — also returned, with code `registration_error`, when the AT registration could not be started",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/V3ServerError"
                    },
                    {
                      "$ref": "#/components/schemas/V3SequenceValidationError"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/sequences/register?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"sequence\":{\"serie_name\":\"INVOICEXPRESSDEMO\"}}'"
          }
        ]
      }
    },
    "/api/v3/clients": {
      "get": {
        "summary": "List Clients",
        "operationId": "listV3Clients",
        "tags": [
          "Clients"
        ],
        "description": "Returns a paginated list of the clients in the account. Archived clients are included unless `status` says otherwise.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "active",
                "archived"
              ],
              "default": "all",
              "example": "active"
            },
            "description": "`active` returns only clients that are not archived, `archived` only archived ones, `all` both. Any other value is treated as `all`. Applies to the rows, the search and the pagination counts."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1,
              "example": 1
            },
            "description": "Page number (default 1)."
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "example": 10
            },
            "description": "Results per page (default 10). `items_per_page` and `page_items` are accepted as aliases."
          },
          {
            "name": "term",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "Acme"
            },
            "description": "Search text. Matches clients whose name, fiscal_id, email or code contains it."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "name",
                "fiscal_id",
                "email",
                "code",
                "created_at",
                "balance"
              ],
              "default": "name"
            },
            "description": "Field to sort by (default `name`). Any other value falls back to `name`."
          },
          {
            "name": "sort_order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ],
              "default": "ASC"
            },
            "description": "Sort direction (default `ASC`, case-insensitive). Any other value falls back to `ASC`."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ClientListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/clients?api_key=YOUR_API_KEY&status=active&page=1&per_page=10&term=Acme&sort=name&sort_order=ASC\""
          }
        ]
      },
      "post": {
        "summary": "Create Client",
        "operationId": "createV3Client",
        "tags": [
          "Clients"
        ],
        "description": "Creates a new client.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateClientRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ClientResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — a field failed validation. When the name or code belongs to an archived client, the error says so (\"An archived contact with this name or code already exists. Unarchive it instead of creating a new one.\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — e.g. the `client` root element is missing\n(`param is missing or the value is empty or invalid: client`), or `initial_balance` was sent inside `client`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/clients?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/clients/suggestions": {
      "get": {
        "summary": "Get Client Suggestions",
        "operationId": "getV3ClientSuggestions",
        "tags": [
          "Clients"
        ],
        "description": "Returns client suggestions. With `client_text`, searches the account's clients by that\ntext. Without it, returns the last clients used on documents of the `document_tab`\nfamily (at most 10, most recent first); an empty list when none were recorded.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "document_tab",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "Invoices",
                "Estimates",
                "Guides"
              ],
              "example": "Invoices"
            },
            "description": "Document family whose last used clients are returned when `client_text` is absent. `documents_tab` is accepted as an alias. Ignored when `client_text` is sent."
          },
          {
            "name": "client_text",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "John"
            },
            "description": "Search text to find clients from the current account."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ClientSuggestionsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/clients/suggestions?api_key=YOUR_API_KEY&document_tab=Invoices&client_text=John\""
          }
        ]
      }
    },
    "/api/v3/clients/{id}": {
      "get": {
        "summary": "Get Client",
        "operationId": "getV3Client",
        "tags": [
          "Clients"
        ],
        "description": "Returns a specific client by ID.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client id"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ClientResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/clients/1?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "put": {
        "summary": "Update Client",
        "operationId": "updateV3Client",
        "tags": [
          "Clients"
        ],
        "description": "Updates an existing client. Partial update — only the keys sent inside `client` are changed.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateClientRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ClientResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — a field failed validation. When the name or code belongs to an archived client, the error says so (\"An archived contact with this name or code already exists. Unarchive it instead of creating a new one.\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — e.g. the `client` root element is missing\n(`param is missing or the value is empty or invalid: client`), or `initial_balance` was sent inside `client`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/clients/1?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      },
      "delete": {
        "summary": "Delete Client",
        "operationId": "deleteV3Client",
        "tags": [
          "Clients"
        ],
        "description": "Deletes a client.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client id"
          }
        ],
        "responses": {
          "204": {
            "description": "SUCCESS"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — client has documents that prevent deletion",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/clients/1?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/clients/{id}/archive": {
      "put": {
        "summary": "Archive Client",
        "operationId": "archiveV3Client",
        "tags": [
          "Clients"
        ],
        "description": "Archives a client. Archiving hides the client from `GET /api/v3/clients?status=active`\nand nothing else: the client can still be read and updated, documents created through\nthe API can still use it, and it still counts when another client is created with the same name or code.\nUse it for clients that cannot be deleted (`can_be_deleted` is `false`), but any client\ncan be archived. No request body. Archiving an archived client succeeds and keeps the\noriginal `archived_at`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client id"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS — the client, with `archived` and `archived_at` updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ClientResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN — the user's role cannot change clients' archive state (guides-only contributors)."
          },
          "404": {
            "description": "NOT FOUND — no client with this id in the account, or the client was deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/clients/12345/archive?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/clients/{id}/unarchive": {
      "put": {
        "summary": "Unarchive Client",
        "operationId": "unarchiveV3Client",
        "tags": [
          "Clients"
        ],
        "description": "Unarchives a client, so it is listed again with `status=active`. No request body.\nUnarchiving a client that is not archived succeeds and changes nothing.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client id"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS — the client, with `archived` and `archived_at` updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ClientResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN — the user's role cannot change clients' archive state (guides-only contributors)."
          },
          "404": {
            "description": "NOT FOUND — no client with this id in the account, or the client was deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/clients/12345/unarchive?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/clients/{id}/balance": {
      "get": {
        "summary": "Get Client Balance",
        "operationId": "getV3ClientBalance",
        "tags": [
          "Clients"
        ],
        "description": "Returns the current account balance for a client.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client id"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ClientBalanceResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/clients/1/balance?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/clients/{id}/initial_balance": {
      "put": {
        "summary": "Update Client Initial Balance",
        "operationId": "updateV3ClientInitialBalance",
        "tags": [
          "Clients"
        ],
        "description": "Updates the initial balance for a client.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3InitialBalanceRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3InitialBalanceResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — validation failed. Possible messages:\n- `Date can't be blank`\n- `Date must be before or equal to the date of the first regularization`\n- `Value must be greater than or equal to the sum of the regularization`\n- `Value must be greater than or equal to 0`\n- `Date must be before or equal to the date of issue of the first document`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — e.g. the `initial_balance` root element is missing\n(`param is missing or the value is empty or invalid: initial_balance`), or `value` is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/clients/1/initial_balance?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/clients/{client_id}/regularization": {
      "get": {
        "summary": "List Client Regularizations",
        "operationId": "listV3ClientRegularizations",
        "tags": [
          "Clients"
        ],
        "description": "Returns the client's regularizations, paginated.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "client_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client id"
          },
          {
            "$ref": "#/components/parameters/V3PageQueryParam"
          },
          {
            "$ref": "#/components/parameters/V3PerPageQueryParam"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Column to sort by.",
            "schema": {
              "type": "string",
              "enum": [
                "treasury_movements.date"
              ],
              "default": "treasury_movements.date",
              "example": "treasury_movements.date"
            }
          },
          {
            "$ref": "#/components/parameters/V3SortOrderQueryParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3RegularizationListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — client not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/clients/12345/regularization?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Create Client Regularization",
        "operationId": "createV3ClientRegularization",
        "tags": [
          "Clients"
        ],
        "description": "Creates a new regularization for a client.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "client_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateRegularizationRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3RegularizationResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — client not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — possible messages:\n- `Invalid root element, expected regularization`\n- `It is not possible to regularize when there is no initial balance`\n- `The regularization amount must be less than or equal to the remaining balance`\n- `Date can't be blank`\n- `Date is invalid`\n- `The date of regularization cannot be before the date of the migrated balance`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/clients/12345/regularization?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/clients/{client_id}/regularization/{id}": {
      "delete": {
        "summary": "Delete Client Regularization",
        "operationId": "deleteV3ClientRegularization",
        "tags": [
          "Clients"
        ],
        "description": "Cancels one or more of the client's regularizations. This is a soft cancel (the movements are marked as canceled, not removed). Ids that are not regularizations of this client are skipped.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "client_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client id"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "1,2,3"
            },
            "description": "Regularization id, or a comma-separated list of ids."
          }
        ],
        "responses": {
          "204": {
            "description": "SUCCESS"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — `Client not found`, or none of the ids is a regularization of this client (`Regularization not found`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/clients/12345/regularization/1?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/clients/{id}/send_open_account_link_mail": {
      "post": {
        "summary": "Send Open Account Link Mail",
        "operationId": "sendV3ClientOpenAccountLinkMail",
        "tags": [
          "Clients"
        ],
        "description": "Sends an open account link email to a chosen client.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3SendOpenAccountLinkMailRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SuccessResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN — email send limit reached for an unverified account (Portuguese account\nwith no série registered with the AT, or whose current série is blank or the demo\nsérie). Checked before the request body is validated. Message:\n`Email service is disabled for your account. To activate it, please contact us at support@invoicexpress.com.`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SendError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Email service is disabled for your account. To activate it, please contact us at support@invoicexpress.com."
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — `Client not found`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — validation or parameter error. Possible messages:\n- `param is missing or the value is empty or invalid: send_open_account_link_mail`\n- `client's email is required`\n- `client save is required`\n- `<address> is an invalid email` (for `client.email`, `cc` or `bcc`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — e.g. the `client` object is missing from `send_open_account_link_mail`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/clients/1/send_open_account_link_mail?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/clients/{client_id}/treasury_movements": {
      "post": {
        "summary": "Create Treasury Movement",
        "operationId": "createV3ClientTreasuryMovement",
        "tags": [
          "Clients"
        ],
        "description": "Creates a new treasury movement for a client.\n\nA `Payment` settles the client's open documents up to `value` and issues a receipt for each.\nA `Reimbursement` is spread over the client's settled documents (or only `document_id` when sent).\n\nSend an `Idempotency-Key` header to make retries safe: a repeated request with the same key and payload\nreplays the first answer instead of creating a second movement.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "client_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client id"
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "example": "6f1c2a4e-1b7d-4c55-9a0e-3f2b8d7c9e10"
            },
            "description": "Optional client-generated unique key (e.g. a UUID). Without it, every request creates a new movement."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateTreasuryMovementRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3TreasuryMovementResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — `Client not found`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "409": {
            "description": "CONFLICT — `A request with this Idempotency-Key is still being processed. Wait for it to finish before retrying.`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — validation failed or invalid parameters. Possible messages:\n- `The receipt amount must be less than or equal to the outstanding balance of the documents.` (`Payment` above the open balance)\n- `Value of reimbursement must be less than or equal to the settled balance of the documents` (`Reimbursement`)\n- `Validation failed: Movement type '<value>' is not a valid type`\n- `Validation failed: Value must be greater than or equal to 0`\n- `This request was already sent with a different payload. Use a new Idempotency-Key for a new payment.`\n- `Invalid root element, expected treasury_movement` (empty body, e.g. `{}`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — e.g. `date` is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/clients/12345/treasury_movements?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/clients/{client_id}/treasury_movements/{id}": {
      "delete": {
        "summary": "Delete Treasury Movement",
        "operationId": "deleteV3ClientTreasuryMovement",
        "tags": [
          "Clients"
        ],
        "description": "Cancels a treasury movement of the client (soft cancel; the movement is marked as canceled, not removed). When the movement has child movements, every child is canceled too.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "client_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Client id"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Treasury movement id"
          }
        ],
        "responses": {
          "204": {
            "description": "SUCCESS"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — `Client not found`, or the movement is not one of this client's (`Reimbursement not found`, whatever the movement type).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Reimbursement not found"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/clients/12345/treasury_movements/1?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/accounts": {
      "get": {
        "summary": "Get Account",
        "operationId": "getV3Account",
        "tags": [
          "Accounts"
        ],
        "description": "Returns the current account details.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3AccountResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/accounts?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Create Account",
        "operationId": "createV3Account",
        "tags": [
          "Accounts"
        ],
        "description": "Creates a new InvoiceXpress account. The response shape depends on whether it is an API or a web request (see the response schema).",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateAccountRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CreateAccountResponse"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE CONTENT",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/accounts\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      },
      "put": {
        "summary": "Update Account",
        "operationId": "updateV3Account",
        "tags": [
          "Accounts"
        ],
        "description": "Updates the current account details. Only the fields sent inside `account` are changed.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateAccountRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3AccountResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. Returned when:\n- the body is empty: no `account` key and no top-level account\n  field (\"Param is missing\"; top-level account fields are wrapped\n  into `account` automatically);\n- the AT rejects `at_subuser`/`at_password` (\"The tax authority\n  rejected the at_subuser/at_password combination\");\n- `fiscal_id` is not valid for the country of a `tax_location_id`\n  other than 1 (\"VAT Number is invalid\");\n- any other field fails validation.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "The tax authority rejected the at_subuser/at_password combination"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/accounts?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/accounts/years_documents": {
      "get": {
        "summary": "Get Years with Documents",
        "operationId": "getV3AccountYearsDocuments",
        "tags": [
          "Accounts"
        ],
        "description": "Returns an array of years that have documents.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3YearsDocumentsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/accounts/years_documents?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/accounts/export": {
      "post": {
        "summary": "Export Account Data",
        "operationId": "exportV3AccountData",
        "tags": [
          "Accounts"
        ],
        "description": "Exports account data in XLS, CSV, or XML format. An email will be sent when the export is ready. Both `data_type` and `data_format` are required; `account` can only be exported as `xml`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "data_type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "account",
                "contacts",
                "invoices",
                "items",
                "inventory"
              ]
            },
            "description": "Data type to export. Missing returns 400; any other value returns 422."
          },
          {
            "name": "data_format",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "csv",
                "xls",
                "xml"
              ]
            },
            "description": "Export file format. Missing returns 400; any other value returns 422. With `data_type=account` only `xml` is accepted (any other format returns 422)."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ExportResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — `data_type` or `data_format` is missing (e.g. \"param is missing or the value is empty or invalid: data_type\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — invalid `data_type` or `data_format`, or `account` with a format other than `xml` (\"Some parameters sent in the request were not valid.\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/accounts/export?api_key=YOUR_API_KEY&data_type=invoices&data_format=xls\""
          }
        ]
      }
    },
    "/api/v3/accounts/billing_history": {
      "get": {
        "summary": "Get Billing History",
        "operationId": "getV3AccountBillingHistory",
        "tags": [
          "Accounts"
        ],
        "description": "Returns InvoiceXpress billing history for the account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "example": 1
            },
            "description": "Page number (default 1)."
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "example": 10
            },
            "description": "Results per page (default 10)."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BillingHistoryResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/accounts/billing_history?api_key=YOUR_API_KEY&page=1&per_page=10\""
          }
        ]
      }
    },
    "/api/v3/accounts/create_already_user": {
      "post": {
        "summary": "Create Account for Existing User",
        "operationId": "createV3AccountAlreadyUser",
        "tags": [
          "Accounts"
        ],
        "description": "Creates a new account for an existing InvoiceXpress user, authenticated by the `email` and `password` in the body. The response shape depends on whether it is an API or a web request (see the response schema).",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateAlreadyUserRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "CREATED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CreateAccountResponse"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE CONTENT. Wrong `email`/`password` (\"Invalid email or password\"), or the account data failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Invalid email or password"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR. Also returned when the `account` key is missing (\"Something went terribly wrong.\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/accounts/create_already_user\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/accounts/at_active_communication": {
      "get": {
        "summary": "Get AT Active Communication",
        "operationId": "getV3AccountATActiveCommunication",
        "tags": [
          "Account Credentials"
        ],
        "description": "Retrieves whether the account has AT communication enabled and the current credentials status.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "context",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "Invoices",
                "Guides",
                "Sequences"
              ],
              "example": "Sequences"
            },
            "description": "The context for which AT communication status is being retrieved."
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "AT"
              ],
              "example": "AT"
            },
            "description": "The credential type. `AT` is the only one."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ATActiveCommunicationResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/accounts/at_active_communication?api_key=YOUR_API_KEY&context=Sequences&type=AT\""
          }
        ]
      }
    },
    "/api/v3/accounts/at_communication": {
      "post": {
        "summary": "Save AT Communication Settings",
        "operationId": "saveV3AccountATCommunication",
        "tags": [
          "Account Credentials"
        ],
        "description": "Saves the AT subuser, AT password, and communication type for an account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3ATCommunicationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SuccessResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. One entry per problem, e.g.:\n- \"The field at_subuser can't be blank\" (empty-string `at_subuser`;\n  an omitted `at_subuser` gives 500)\n- \"The field at_password can't be blank\"\n- \"The field communication_type can't be blank\"\n- `The field communication_type can't be <value>`\n- \"at_subuser must contain /\"\n- \"The field at_subuser format is incorrect\"\n- \"The field at_subuser has an incorrect size\"\n- \"The tax authority rejected the at_subuser/at_password combination\"\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "The field at_subuser can't be blank"
                    },
                    {
                      "error": "The field at_password can't be blank"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR. Also returned when the `at_communication` key is missing, and when `at_subuser` is omitted with a `communication_type` other than `manual` (\"undefined method 'include?' for nil\"). An empty-string `at_subuser` gives 422 instead.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/accounts/at_communication?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/accounts/at_communication_history": {
      "get": {
        "summary": "Get AT Communication History",
        "operationId": "getV3AccountATCommunicationHistory",
        "tags": [
          "Account Credentials"
        ],
        "description": "Returns the AT communication history for the account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "example": 1
            },
            "description": "Page number (default 1)."
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "example": 10
            },
            "description": "Results per page (default 10)."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ATCommunicationHistoryResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "503": {
            "description": "SERVICE UNAVAILABLE — the history query hit its 15-second time limit (`Couldn't complete request`). Sent with a `Retry-After` header (30 seconds).",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 30
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Couldn't complete request"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/accounts/at_communication_history?api_key=YOUR_API_KEY&page=1&per_page=10\""
          }
        ]
      }
    },
    "/api/v3/accounts/settings": {
      "get": {
        "summary": "Get Account Settings",
        "operationId": "getV3AccountSettings",
        "tags": [
          "Accounts"
        ],
        "description": "Returns the account configuration settings for one documents tab, chosen with the required `documents_tab` query parameter.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "documents_tab",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "Invoice",
                "Estimate",
                "Guide",
                "Schedule"
              ],
              "example": "Invoice"
            },
            "description": "Documents tab whose settings are returned. Plural and lowercase forms are also accepted (`invoices`, `estimate`, `guides`, ...); they are singularized and capitalized. Any other value returns 422 (`Tab <value> doesn't exist`); omitting the parameter returns 500."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3AccountSettingsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. Unknown `documents_tab`. Note that `errors` is an object here, not an array.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string",
                          "example": "Tab foo doesn't exist"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR. Also returned when `documents_tab` is missing (\"Something went terribly wrong.\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/accounts/settings?api_key=YOUR_API_KEY&documents_tab=Invoice\""
          }
        ]
      }
    },
    "/api/v3/accounts/users": {
      "get": {
        "summary": "List Account Users",
        "operationId": "listV3AccountUsers",
        "tags": [
          "Accounts"
        ],
        "description": "Returns the account's users, paginated.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "$ref": "#/components/parameters/V3PageQueryParam"
          },
          {
            "$ref": "#/components/parameters/V3PerPageQueryParam"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Field to sort by.",
            "schema": {
              "type": "string",
              "enum": [
                "users.id",
                "users.email"
              ],
              "default": "users.id",
              "example": "users.email"
            }
          },
          {
            "$ref": "#/components/parameters/V3SortOrderQueryParam"
          },
          {
            "name": "term",
            "in": "query",
            "required": false,
            "description": "Returns only users whose email contains this text.",
            "schema": {
              "type": "string",
              "example": "@example.com"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3AccountUsersResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/accounts/users?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Create or Add Account User",
        "operationId": "createV3AccountUser",
        "tags": [
          "Accounts"
        ],
        "description": "Creates a new user or adds an existing user to the account. `user.role` is optional; a missing or unknown role gives the user the `contributor` role.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateAccountUserRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3AccountUserResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN — account user limit reached for current plan",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — validation failed, the `user` key is missing, or the user is already on the account (\"The user has already been added to the account.\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/accounts/users?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/accounts/users/{id}": {
      "put": {
        "summary": "Update Account User",
        "operationId": "updateV3AccountUser",
        "tags": [
          "Accounts"
        ],
        "description": "Updates a user's role on the account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "User id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateAccountUserRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3AccountUserResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND. The user is not on the account (\"User not found.\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "User not found."
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. `user.role` is missing or is not a valid role (\"Role is invalid\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Role is invalid"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR (\"Something went terribly wrong.\"). A JSON body without the `user` key is wrapped into `user` automatically, so it fails with 422 \"Role is invalid\" rather than 500.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/accounts/users/1?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"user\":{\"role\":\"administrator\"}}'"
          }
        ]
      },
      "delete": {
        "summary": "Remove Account User",
        "operationId": "deleteV3AccountUser",
        "tags": [
          "Accounts"
        ],
        "description": "Removes one or more users from the account. Ids that are not users of this account are skipped.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "12,34"
            },
            "description": "User id, or a comma-separated list of user ids."
          }
        ],
        "responses": {
          "204": {
            "description": "SUCCESS"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN — the list includes your own user (`Request not allowed.`). Nobody is removed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — none of the ids is a user of this account (`User not found.`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/accounts/users/1?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/accounts/document_customization": {
      "get": {
        "summary": "Get Document Customization",
        "operationId": "getV3DocumentCustomization",
        "tags": [
          "Accounts"
        ],
        "description": "Returns the document customization of the account, or of one série with `serie_name`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "serie_name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "2026"
            },
            "description": "Name of a série of the account. When sent, the customization of that série is returned instead of the account's, and `has_series_configuration` says whether the série has its own customization."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DocumentCustomizationResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/accounts/document_customization?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "put": {
        "summary": "Update Document Customization",
        "operationId": "updateV3DocumentCustomization",
        "tags": [
          "Accounts"
        ],
        "description": "Replaces the document customization of the account (or of one série,\nwith `serie_name`).\n\n**This is a full replace:** every customization field that is not sent\n(or is sent blank) is set to `null`. Send all the values you want to\nkeep, not only the ones you change. See the request body for the list\nof fields.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateDocumentCustomizationRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateDocumentCustomizationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS. When the logo could not be stored, the body also has `logo_error`; every other field was saved and the previous logo was kept.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UpdateDocumentCustomizationResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. A field failed validation, or the uploaded logo is not valid, with the error `image_not_valid`. A logo must be a `png`, `jpeg` or `jpg` file the server can decode, of at most 200 KB and 1000 × 1000 pixels. Nothing is saved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UpdateDocumentCustomizationError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/accounts/document_customization?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"email\":\"billing@example.com\",\"phone\":\"213456789\",\"website\":\"https://example.com\",\"phone_country_id\":1,\"tax_exemption_code\":\"M07\",\"remarks\":\"Thank you for your business.\",\"footer\":\"Company registered in Lisbon.\",\"document_copies\":2,\"payment_days\":15,\"bank_data_type_1\":\"IBAN\",\"bank_data_value_1\":\"PT50000201231234567890154\"}'"
          }
        ]
      },
      "delete": {
        "summary": "Remove Logo",
        "operationId": "deleteV3AccountLogo",
        "tags": [
          "Accounts"
        ],
        "description": "Removes the account logo, or, with `serie_name`, the logo of that série only.\nAlways answers 200: `{\"success\": true}`, also when there was no logo to remove.\nAfter an internal failure it still answers 200, but the body is not\n`{\"success\": true}`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "serie_name",
            "in": "query",
            "required": false,
            "description": "Name of the série whose logo is removed. Omit it to remove the account logo.",
            "schema": {
              "type": "string",
              "example": "SERIE2026"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SuccessResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/accounts/document_customization?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/account_credentials": {
      "post": {
        "summary": "Create AT Communication Details",
        "operationId": "createV3AccountCredentials",
        "tags": [
          "Account Credentials"
        ],
        "description": "Creates AT communication details for an account. The credentials are checked against the AT before they are stored.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3AccountCredentialRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3AccountCredentialCreatedResponse"
                }
              }
            }
          },
          "409": {
            "description": "Conflict — the account already has credentials (`Already has credentials for this context`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3AccountCredentialMessageError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — missing `account_credential` root or required fields, `username` not matching the account NIF (an account without a NIF also lands here, as `subuser_unmatch_nif`), AT credentials rejected, or `use_legacy_credentials` with no legacy credentials to copy. `User doesn't have fiscal id associated` exists but is rarely reachable.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/V3AccountCredentialErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/V3AccountCredentialMessageError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/account_credentials?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      },
      "put": {
        "summary": "Update AT Communication Details",
        "operationId": "updateV3AccountCredentials",
        "tags": [
          "Account Credentials"
        ],
        "description": "Updates the AT communication details stored for the given `context` and `type`. `username` and `password` are always required here, and are checked against the AT before they are stored.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3AccountCredentialRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ok",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3AccountCredentialCreatedResponse"
                }
              }
            }
          },
          "404": {
            "description": "RECORD NOT FOUND — no credentials stored for this `context` and `type` (`No credentials to update`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3AccountCredentialMessageError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — missing `account_credential` root or required fields, `username` not matching the account NIF, or AT credentials rejected",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/V3AccountCredentialErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/V3AccountCredentialMessageError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/account_credentials?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/collection_alerts": {
      "post": {
        "summary": "Create Collection Alert",
        "operationId": "createV3CollectionAlert",
        "tags": [
          "Collection Alerts"
        ],
        "description": "Creates the collection alert configuration of the account, or of a client when `client_id` is sent. At account level, `replicate=true` deletes every client-level configuration.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateCollectionAlertRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CollectionAlertResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND. Unknown `client_id` (\"Client not found\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Client not found"
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. The `collection_alert` key is missing, or an enum field has a value outside its list (e.g. \"'yearly' is not a valid frequency\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/collection_alerts?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      },
      "put": {
        "summary": "Update Collection Alert",
        "operationId": "updateV3CollectionAlert",
        "tags": [
          "Collection Alerts"
        ],
        "description": "Updates the existing collection alert configuration of the account, or\nof a client when `client_id` is sent.\n\n- Account level, `replicate=true`: every client-level configuration is\n  deleted, so all clients follow the account configuration.\n- Client level, `replicate=true`: the client's own configuration is\n  deleted (the client falls back to the account configuration), the\n  other fields are ignored, and the response is\n  `{\"collection_alert\": {\"client_has_email\": true|false}}`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateCollectionAlertRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CollectionAlertResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND. There is no configuration to update for the account (or for the client) (\"Configuration not found\"), or the `client_id` is unknown (\"Client not found\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Configuration not found"
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. An enum field has a value outside its list (e.g. \"'yearly' is not a valid frequency\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR. Also returned when there is an existing configuration and the body has no `collection_alert` (empty body; top-level fields are wrapped into `collection_alert` automatically).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/collection_alerts?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      },
      "get": {
        "summary": "Get Collection Alert",
        "operationId": "getV3CollectionAlert",
        "tags": [
          "Collection Alerts"
        ],
        "description": "Returns the collection alert configuration for an account or client.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "client_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "The client id. When sent, the client's own configuration is returned."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS. With `client_id` and no configuration for that client, the\nbody is only `{\"collection_alert\": {\"client_has_email\": true|false}}`.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CollectionAlertResponse"
                },
                "examples": {
                  "configured": {
                    "summary": "Configuration found",
                    "value": {
                      "collection_alert": {
                        "configurable": "Client",
                        "frequency": "biweekly",
                        "weekday": "monday",
                        "period": "morning",
                        "due": "before_overdue",
                        "email": true,
                        "sms": false,
                        "email_template": "This is an email\nwith a break line",
                        "sms_template": null,
                        "client_has_email": true
                      }
                    }
                  },
                  "clientWithoutConfiguration": {
                    "summary": "client_id sent, no configuration for that client",
                    "value": {
                      "collection_alert": {
                        "client_has_email": true
                      }
                    }
                  }
                }
              }
            }
          },
          "204": {
            "description": "NO CONTENT — no collection alert is configured for the account (request without `client_id`). The response body is empty (zero bytes), not a JSON document."
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND. Unknown `client_id` (\"Client not found\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Client not found"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/collection_alerts?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/invoices": {
      "get": {
        "summary": "Get Current Batch Invoice Job",
        "operationId": "getV3BatchInvoiceJob",
        "tags": [
          "Batch Invoices"
        ],
        "description": "Returns the most recent non-expired batch invoice metadata. Returns 204 if no active batch exists.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS — Returns the active batch invoice metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchInvoiceMetadataResponse"
                }
              }
            }
          },
          "204": {
            "description": "NO CONTENT — No active batch invoice job exists"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/invoices?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Start Batch Invoice Creation",
        "operationId": "createV3BatchInvoices",
        "tags": [
          "Batch Invoices"
        ],
        "description": "Enqueues a background job to create invoices from validated batch previews. Requires an active batch in \"validated\" status.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "202": {
            "description": "ACCEPTED — Batch invoice job enqueued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ImportJobResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "409": {
            "description": "CONFLICT — Batch job already running",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Batch not validated or has invalid previews",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/imports/invoices?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "delete": {
        "summary": "Delete Active Batch Invoice Job",
        "operationId": "deleteV3BatchInvoiceJob",
        "tags": [
          "Batch Invoices"
        ],
        "description": "Destroys the currently active batch invoice job and associated S3 files.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "204": {
            "description": "NO CONTENT — Batch destroyed successfully"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/imports/invoices?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/invoices/template": {
      "get": {
        "summary": "Get Batch Invoice CSV Template",
        "operationId": "getV3BatchInvoiceTemplate",
        "tags": [
          "Batch Invoices"
        ],
        "description": "Returns a presigned S3 URL to download the batch invoice CSV template. Language matches the account language (en, es, pt).",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS — JSON with presigned download URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ImportTemplateResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — Could not generate presigned URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/template?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/invoices/configure_options": {
      "get": {
        "summary": "Get Batch Invoice Configuration Options",
        "operationId": "getV3BatchInvoiceConfigureOptions",
        "tags": [
          "Batch Invoices"
        ],
        "description": "Returns data for populating the configure step dropdowns (sequences, exemption reasons). Only series registered with the AT are listed.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS — Configuration options returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchInvoiceConfigureOptions"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/configure_options?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/invoices/upload": {
      "post": {
        "summary": "Upload CSV for Batch Invoice Import",
        "operationId": "uploadV3BatchInvoiceCSV",
        "tags": [
          "Batch Invoices"
        ],
        "description": "Validates the CSV file and uploads it to S3. Creates a new batch metadata record.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "CSV file to import (max 10 MB)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "CREATED — File uploaded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchInvoiceUploadResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — the `file` part is missing\n(`param is missing or the value is empty or invalid: file`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "param is missing or the value is empty or invalid: file"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Invalid file, too large, or invalid CSV format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/upload?api_key=YOUR_API_KEY\" -F \"file=@import.csv\""
          }
        ]
      }
    },
    "/api/v3/imports/invoices/process": {
      "post": {
        "summary": "Process Uploaded CSV (Batch Invoice Mapping)",
        "operationId": "processV3BatchInvoiceCSV",
        "tags": [
          "Batch Invoices"
        ],
        "description": "After uploading, call this with separator and header info to build the column mapping.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3ProcessRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "CREATED — Batch processed, mapping returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchInvoiceProcessResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — Missing or empty `process` wrapper (e.g. \"param is missing or the value is empty or invalid: process\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch (\"No active batch found for import\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Invalid CSV or invalid separator",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/process?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"process\":{\"separator\":\"auto\",\"exclude_first_line\":true}}'"
          }
        ]
      }
    },
    "/api/v3/imports/invoices/mapping": {
      "get": {
        "summary": "Get CSV Column Mapping",
        "operationId": "getV3BatchInvoiceMapping",
        "tags": [
          "Batch Invoices"
        ],
        "description": "Returns the CSV column-to-field mapping for the active batch invoice job.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — Returns the header mapping",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3InvoiceMappingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch or mapping not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/mapping?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "put": {
        "summary": "Save CSV Column Mapping",
        "operationId": "saveV3BatchInvoiceMapping",
        "tags": [
          "Batch Invoices"
        ],
        "description": "Saves the user-selected column-to-field mapping for the active batch invoice job.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3InvoiceMappingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — Mapping saved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3InvoiceMappingResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — Missing mapping parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Invalid mapping or required fields not mapped",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/mapping?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/imports/invoices/configure": {
      "put": {
        "summary": "Configure Batch Invoice Job",
        "operationId": "configureV3BatchInvoiceJob",
        "tags": [
          "Batch Invoices"
        ],
        "description": "Updates the active batch invoice job with configuration options (name, document type, sequence, etc.) and transitions status to \"configured\".",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3BatchInvoiceConfigureRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS — Batch configured successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchInvoiceConfigureResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — Missing required parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/configure?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/imports/invoices/validate": {
      "post": {
        "summary": "Start Batch Invoice CSV Validation",
        "operationId": "validateV3BatchInvoices",
        "tags": [
          "Batch Invoices"
        ],
        "description": "Enqueues a background job to validate the CSV rows. Requires batch in \"configured\" status. Poll GET /api/v3/imports/invoices/validation for results.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "202": {
            "description": "ACCEPTED — Validation job enqueued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidateJobResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "409": {
            "description": "CONFLICT — A validation is already running for this batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Batch not configured or CSV/mapping missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/validate?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/invoices/validation": {
      "get": {
        "summary": "Get Batch Invoice Validation Status",
        "operationId": "getV3BatchInvoiceValidation",
        "tags": [
          "Batch Invoices"
        ],
        "description": "Poll this after POST /api/v3/imports/invoices/validate to get validation status and result.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — Validation completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidationStatusResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED — Validation still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidationProcessingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Validation failed, or the batch has not been validated yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidationFailedResponse"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — Validation job stuck, status not found, or status check failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidationErrorResponse"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/validation?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/invoices/available_docs": {
      "get": {
        "summary": "Check Document Quota",
        "operationId": "getV3BatchInvoiceAvailableDocs",
        "tags": [
          "Batch Invoices"
        ],
        "description": "Returns whether the account has enough document quota to create invoices from validated previews. Use before POST /api/v3/imports/invoices.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — Availability check result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3AvailableDocsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — No valid previews or unable to check",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/available_docs?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/invoices/status": {
      "get": {
        "summary": "Get Batch Invoice Creation Status",
        "operationId": "getV3BatchInvoiceStatus",
        "tags": [
          "Batch Invoices"
        ],
        "description": "Poll after POST /api/v3/imports/invoices to check invoice creation progress. Status values — processing (202), sending_email (202), completed (200), failed / exception_occurred / interrupted (422), stuck/unknown (500). Every body carries a `success` boolean.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — Batch invoice creation completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchStatusCompletedResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED — Batch invoice job still in progress",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchStatusProcessingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Batch invoice creation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchStatusFailedResponse"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — Status unknown or batch job stuck",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchStatusUnknownResponse"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/invoices/status?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/products": {
      "get": {
        "summary": "Get Current Batch Product Import Job",
        "operationId": "getV3BatchProductJob",
        "tags": [
          "Batch Products"
        ],
        "description": "Returns the most recent non-expired batch product import metadata. Returns 204 if no active batch exists.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS — Returns the active batch product import metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchInvoiceMetadataResponse"
                }
              }
            }
          },
          "204": {
            "description": "NO CONTENT — No active batch product import job exists"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/products?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Start Batch Product Import",
        "operationId": "createV3BatchProducts",
        "tags": [
          "Batch Products"
        ],
        "description": "Enqueues a background job to create products from validated batch previews. Poll GET /api/v3/imports/products/status for completion.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "202": {
            "description": "ACCEPTED — Product import job enqueued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ImportJobResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "409": {
            "description": "CONFLICT — Import job already running",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Batch not validated or has invalid previews",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/imports/products?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "delete": {
        "summary": "Delete Active Batch Product Import Job",
        "operationId": "deleteV3BatchProductJob",
        "tags": [
          "Batch Products"
        ],
        "description": "Destroys the currently active batch product import and associated S3 files.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "204": {
            "description": "NO CONTENT — Batch destroyed successfully"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/imports/products?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/products/template": {
      "get": {
        "summary": "Get Batch Product CSV Template",
        "operationId": "getV3BatchProductTemplate",
        "tags": [
          "Batch Products"
        ],
        "description": "Returns a presigned S3 URL to download the batch product CSV template.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS — JSON with presigned download URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ImportTemplateResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — Could not generate presigned URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/products/template?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/products/status": {
      "get": {
        "summary": "Get Batch Product Import Status",
        "operationId": "getV3BatchProductStatus",
        "tags": [
          "Batch Products"
        ],
        "description": "Returns the current status of the batch product import job. Poll after POST /api/v3/imports/products.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — Batch product import completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ProductBatchStatusCompletedResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED — Import still running",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CatalogImportProcessingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Import failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CatalogImportFailedResponse"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — Stuck or unknown. Note the response body does not use the usual errors-array shape — it mirrors the status polling shape with success/status/message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchStatusUnknownResponse"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/products/status?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/products/upload": {
      "post": {
        "summary": "Upload CSV for Batch Product Import",
        "operationId": "uploadV3BatchProductCSV",
        "tags": [
          "Batch Products"
        ],
        "description": "Validates the CSV file and uploads it to S3. Creates a new batch metadata record with import type products.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "CSV file to import (max 10 MB)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "CREATED — File uploaded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchInvoiceUploadResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — the `file` part is missing\n(`param is missing or the value is empty or invalid: file`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "param is missing or the value is empty or invalid: file"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Invalid file, too large, or invalid CSV format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/imports/products/upload?api_key=YOUR_API_KEY\" -F \"file=@import.csv\""
          }
        ]
      }
    },
    "/api/v3/imports/products/process": {
      "post": {
        "summary": "Process Uploaded CSV (Batch Product Mapping)",
        "operationId": "processV3BatchProductCSV",
        "tags": [
          "Batch Products"
        ],
        "description": "After uploading, call this with separator and header info to build the product field mapping.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3ProcessRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "CREATED — Batch processed, mapping returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchProductProcessResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — Missing or empty `process` wrapper (e.g. \"param is missing or the value is empty or invalid: process\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active product import batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Invalid CSV or separator",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/imports/products/process?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"process\":{\"separator\":\"auto\",\"exclude_first_line\":true}}'"
          }
        ]
      }
    },
    "/api/v3/imports/products/mapping": {
      "get": {
        "summary": "Get CSV Column Mapping for Product Import",
        "operationId": "getV3BatchProductMapping",
        "tags": [
          "Batch Products"
        ],
        "description": "Returns the CSV column-to-field mapping for the active batch product import.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — Returns the header mapping",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ProductMappingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch or mapping not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/products/mapping?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "put": {
        "summary": "Save CSV Column Mapping for Product Import",
        "operationId": "saveV3BatchProductMapping",
        "tags": [
          "Batch Products"
        ],
        "description": "Saves the user-selected column-to-field mapping for the active batch product import.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3ProductMappingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — Mapping saved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ProductMappingResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — Missing mapping parameter"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Invalid column or required field not mapped",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/imports/products/mapping?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/imports/products/validate": {
      "post": {
        "summary": "Start Batch Product CSV Validation",
        "operationId": "validateV3BatchProducts",
        "tags": [
          "Batch Products"
        ],
        "description": "Enqueues a background job to validate the CSV rows. Requires batch in \"mapping\" status. Poll GET /api/v3/imports/products/validation for results.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "202": {
            "description": "ACCEPTED — Validation job enqueued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidateJobResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "409": {
            "description": "CONFLICT — A validation is already running",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Batch not ready for validation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/imports/products/validate?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/products/validation": {
      "get": {
        "summary": "Get Batch Product Validation Status",
        "operationId": "getV3BatchProductValidation",
        "tags": [
          "Batch Products"
        ],
        "description": "Poll after POST /api/v3/imports/products/validate to get validation status and result.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — Validation completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidationStatusResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED — Validation still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidationProcessingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Validation failed, or the batch has not been validated yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidationFailedResponse"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — Validation job stuck, status not found, or status check failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidationErrorResponse"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/products/validation?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/clients": {
      "get": {
        "summary": "Get Current Batch Client Import Job",
        "operationId": "getV3BatchClientJob",
        "tags": [
          "Batch Clients"
        ],
        "description": "Returns the most recent non-expired batch client import metadata. Returns 204 if no active batch exists.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS — Returns the active batch client import metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchInvoiceMetadataResponse"
                }
              }
            }
          },
          "204": {
            "description": "NO CONTENT — No active batch client import job exists"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/clients?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Start Batch Client Import",
        "operationId": "createV3BatchClients",
        "tags": [
          "Batch Clients"
        ],
        "description": "Enqueues a background job to create clients from validated batch previews. Poll GET /api/v3/imports/clients/status for completion.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "202": {
            "description": "ACCEPTED — Client import job enqueued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ImportJobResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "409": {
            "description": "CONFLICT — Import job already running",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Batch not validated or has invalid previews",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/imports/clients?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "delete": {
        "summary": "Delete Active Batch Client Import Job",
        "operationId": "deleteV3BatchClientJob",
        "tags": [
          "Batch Clients"
        ],
        "description": "Destroys the currently active batch client import and associated S3 files.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "204": {
            "description": "NO CONTENT — Batch destroyed successfully"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/imports/clients?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/clients/status": {
      "get": {
        "summary": "Get Batch Client Import Status",
        "operationId": "getV3BatchClientStatus",
        "tags": [
          "Batch Clients"
        ],
        "description": "Returns the current status of the batch client import job. Poll after POST /api/v3/imports/clients.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — Batch client import completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ProductBatchStatusCompletedResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED — Import still running",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CatalogImportProcessingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Import failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CatalogImportFailedResponse"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — Stuck or unknown. Note the response body does not use the usual errors-array shape — it mirrors the status polling shape with success/status/message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchStatusUnknownResponse"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/clients/status?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/clients/template": {
      "get": {
        "summary": "Get Batch Client CSV Template",
        "operationId": "getV3BatchClientTemplate",
        "tags": [
          "Batch Clients"
        ],
        "description": "Returns a presigned S3 URL to download the batch client CSV template.\nRequired column: name. All other columns (including fiscal_id) are optional.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS — JSON with presigned download URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ImportTemplateResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — Could not generate presigned URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/clients/template?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/clients/upload": {
      "post": {
        "summary": "Upload CSV for Batch Client Import",
        "operationId": "uploadV3BatchClientCSV",
        "tags": [
          "Batch Clients"
        ],
        "description": "Validates the CSV file and uploads it to S3. Creates a new batch metadata record with import type clients.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "CSV file to import (max 10 MB)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "CREATED — File uploaded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchInvoiceUploadResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — the `file` part is missing\n(`param is missing or the value is empty or invalid: file`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "param is missing or the value is empty or invalid: file"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Invalid file, too large, or invalid CSV format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/imports/clients/upload?api_key=YOUR_API_KEY\" -F \"file=@import.csv\""
          }
        ]
      }
    },
    "/api/v3/imports/clients/process": {
      "post": {
        "summary": "Process Uploaded CSV (Batch Client Mapping)",
        "operationId": "processV3BatchClientCSV",
        "tags": [
          "Batch Clients"
        ],
        "description": "After uploading, call this with separator and header info to build the client field mapping.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3ProcessRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "CREATED — Batch processed, mapping returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BatchClientProcessResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — Missing or empty `process` wrapper (e.g. \"param is missing or the value is empty or invalid: process\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active client import batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Invalid CSV or separator",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/imports/clients/process?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"process\":{\"separator\":\"auto\",\"exclude_first_line\":true}}'"
          }
        ]
      }
    },
    "/api/v3/imports/clients/mapping": {
      "get": {
        "summary": "Get CSV Column Mapping for Client Import",
        "operationId": "getV3BatchClientMapping",
        "tags": [
          "Batch Clients"
        ],
        "description": "Returns the CSV column-to-field mapping for the active batch client import.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — Returns the header mapping",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ClientMappingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch or mapping not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/clients/mapping?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "put": {
        "summary": "Save CSV Column Mapping for Client Import",
        "operationId": "saveV3BatchClientMapping",
        "tags": [
          "Batch Clients"
        ],
        "description": "Saves the user-selected column-to-field mapping for the active batch client import.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3ClientMappingRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK — Mapping saved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ClientMappingResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — Missing mapping parameter"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Invalid column or required field not mapped",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/imports/clients/mapping?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/imports/clients/validate": {
      "post": {
        "summary": "Start Batch Client CSV Validation",
        "operationId": "validateV3BatchClients",
        "tags": [
          "Batch Clients"
        ],
        "description": "Enqueues a background job to validate the CSV rows. Requires batch in \"mapping\" status. Poll GET /api/v3/imports/clients/validation for results.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "202": {
            "description": "ACCEPTED — Validation job enqueued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidateJobResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "409": {
            "description": "CONFLICT — A validation is already running",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Batch not ready for validation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/imports/clients/validate?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/imports/clients/validation": {
      "get": {
        "summary": "Get Batch Client Validation Status",
        "operationId": "getV3BatchClientValidation",
        "tags": [
          "Batch Clients"
        ],
        "description": "Poll after POST /api/v3/imports/clients/validate to get validation status and result.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "OK — Validation completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidationStatusResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED — Validation still processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidationProcessingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — No active batch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — Validation failed, or the batch has not been validated yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidationFailedResponse"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — Validation job stuck, status not found, or status check failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ValidationErrorResponse"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/imports/clients/validation?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/items": {
      "get": {
        "summary": "List Items",
        "operationId": "listV3Items",
        "tags": [
          "Items"
        ],
        "description": "Returns a paginated list of all items (products/services) in the account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1,
              "example": 1
            },
            "description": "Page number (default 1)."
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 10,
              "example": 10
            },
            "description": "Results per page (default 10). `items_per_page` and `page_items` are accepted as aliases."
          },
          {
            "name": "term",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "Consult"
            },
            "description": "Search text. Matches items whose name (`code`) or description contains it."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "products.name",
                "description",
                "unit_price",
                "rrp",
                "unit",
                "created_at"
              ],
              "default": "products.name",
              "example": "unit_price"
            },
            "description": "Field to sort by (default `products.name`)."
          },
          {
            "name": "sort_order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC",
                "asc",
                "desc"
              ],
              "default": "ASC"
            },
            "description": "Sort direction (default `ASC`)."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ItemListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — `Something went terribly wrong.` (e.g. an unknown `sort` column or an invalid `sort_order`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/items?api_key=YOUR_API_KEY&page=1&per_page=10&term=Consult&sort=name&sort_order=ASC\""
          }
        ]
      },
      "post": {
        "summary": "Create Item",
        "operationId": "createV3Item",
        "tags": [
          "Items"
        ],
        "description": "Creates a new item (product or service). When omitted, `unit` defaults to `service`, the tax defaults to the account's default tax and `rrp` is computed from `unit_price` and the tax.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateItemRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ItemResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — validation failed. Examples:\n- `Tax must exist` (unknown `tax.name`)\n- `Price is not valid. Check the decimal mark and if you are inserting only numbers.` (missing or non-numeric `unit_price`)\n- `Code for the item is too long (maximum should be 60 characters)`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — `Something went terribly wrong.` (e.g. an empty body, with no `item` root and no top-level item field). Top-level fields are wrapped into `item` automatically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/items?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/items/{id}": {
      "get": {
        "summary": "Get Item",
        "operationId": "getV3Item",
        "tags": [
          "Items"
        ],
        "description": "Returns a specific item with detailed sales statistics.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Item id"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ItemDetailResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/items/1?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "put": {
        "summary": "Update Item",
        "operationId": "updateV3Item",
        "tags": [
          "Items"
        ],
        "description": "Updates an existing item. Partial update — only the keys sent inside `item` are changed, except `retention`, which is reset to `0` when omitted. An unknown `tax.name` is ignored (the current tax is kept).",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Item id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateItemRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ItemResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — `Item not found.`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — validation failed. Examples:\n- `Code can't be changed because it is already associated with invoices`\n- `Code for the item is too long (maximum should be 60 characters)`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — `Something went terribly wrong.` (e.g. an empty body, with no `item` root and no top-level item field). Top-level fields are wrapped into `item` automatically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/items/1?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      },
      "delete": {
        "summary": "Delete Item",
        "operationId": "deleteV3Item",
        "tags": [
          "Items"
        ],
        "description": "Deletes one or more items. This is a soft delete (the items are marked as deleted, not removed). Ids that are not undeleted items of the account are skipped.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "1,2,3"
            },
            "description": "Item id, or a comma-separated list of item ids."
          }
        ],
        "responses": {
          "204": {
            "description": "NO CONTENT"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — none of the ids is an undeleted item of the account (`Item not found.`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Item not found."
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/items/1?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/schedules": {
      "get": {
        "summary": "List Schedules",
        "operationId": "listV3Schedules",
        "tags": [
          "Schedules"
        ],
        "description": "Returns a paginated list of all recurring document schedules for the account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "description": "Page number."
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 10
            },
            "description": "Schedules per page. `items_per_page` and `page_items` are accepted as aliases."
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "client_name",
                "next_date",
                "end_date"
              ],
              "default": "client_name"
            },
            "description": "Sort field. Any other value falls back to `client_name`."
          },
          {
            "name": "sort_order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ],
              "default": "ASC"
            },
            "description": "Sort direction (case-insensitive). Any other value falls back to `ASC`."
          },
          {
            "name": "term",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Free-text filter matched (LIKE) against the schedule description, the client's name, code, email, fiscal_id, address, country, phone, fax and postal code, and the template's item names and descriptions."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ScheduleListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/schedules?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Create Schedule",
        "operationId": "createV3Schedule",
        "tags": [
          "Schedules"
        ],
        "description": "Creates a new recurring document schedule. `start_date` must be tomorrow or later, so no back invoices are produced on create.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateScheduleRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ScheduleResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — Empty body (no `schedule` root and no top-level schedule field; ActionController::ParameterMissing; no JSON error body is guaranteed). Top-level schedule fields are wrapped into `schedule` automatically; `template` is not a schedule field and must be sent inside `schedule`."
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE CONTENT — e.g. `start_date` is today or in the past (\"Start date cannot be today, must be tomorrow or later\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/schedules?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/schedules/{id}": {
      "get": {
        "summary": "Get Schedule",
        "operationId": "getV3Schedule",
        "tags": [
          "Schedules"
        ],
        "description": "Returns a specific schedule with its template.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Schedule id"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ScheduleResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/schedules/1?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "put": {
        "summary": "Update Schedule",
        "operationId": "updateV3Schedule",
        "tags": [
          "Schedules"
        ],
        "description": "Updates an existing schedule. This is not a partial update; resend the full schedule, including `template` with its `client` and `items`. A missing `template` or `items` answers 422 (`No template element provided`, `No items element provided`). `No client element provided` (422) is returned only when `client` is sent without an `id`, `name` or `code`, not when it is missing.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Schedule id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateScheduleRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ScheduleResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — Empty body (no `schedule` root and no top-level schedule field; ActionController::ParameterMissing; no JSON error body is guaranteed). Top-level schedule fields are wrapped into `schedule` automatically; `template` is not a schedule field and must be sent inside `schedule`."
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE CONTENT",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/schedules/1?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      },
      "delete": {
        "summary": "Archive Schedule",
        "operationId": "archiveV3Schedule",
        "tags": [
          "Schedules"
        ],
        "description": "Archives (soft-deletes) a schedule in the account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Schedule id"
          }
        ],
        "responses": {
          "200": {
            "description": "Archived",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ScheduleResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/schedules/1?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/schedules/{id}/timeline": {
      "get": {
        "summary": "Get Schedule Timeline",
        "operationId": "getV3ScheduleTimeline",
        "tags": [
          "Schedules"
        ],
        "description": "Retrieves the timeline activities of a specific schedule (creation, updates, status changes). Schedules have no comments, so none are included.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Schedule id"
          }
        ],
        "responses": {
          "200": {
            "description": "Timeline activities retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ScheduleTimelineResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/schedules/1/timeline?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/schedules/{id}/toggle": {
      "put": {
        "summary": "Toggle Schedule Active State",
        "operationId": "toggleV3Schedule",
        "tags": [
          "Schedules"
        ],
        "description": "Activates or deactivates a schedule.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Schedule id"
          }
        ],
        "responses": {
          "200": {
            "description": "Activated/Deactivated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ScheduleResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/schedules/1/toggle?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/taxes": {
      "get": {
        "summary": "List Taxes",
        "operationId": "listV3Taxes",
        "tags": [
          "Taxes"
        ],
        "description": "Returns a list of all tax rates for the account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3TaxListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/taxes?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Create Tax",
        "operationId": "createV3Tax",
        "tags": [
          "Taxes"
        ],
        "description": "Creates a new tax rate.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateTaxRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3TaxResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — one entry per failed validation. English messages:\n- `Name can't be blank`\n- `Name is not available.` (another tax of the account has this name)\n- `Value can't be blank`\n- `Value is not a number`\n- `Value should be greater or equal to 0`\n- `Value must be less than or equal to 100`\n- `Region can't be empty` (unless `name` is `Isento`)\n- `Region the field must be one of the following values: AD|AE|...|PT-AC|PT-MA.`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Value must be less than or equal to 100"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — `Something went terribly wrong.` (e.g. an empty body, with no `tax` root and no top-level tax field). Top-level fields are wrapped into `tax` automatically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/taxes?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/taxes/{id}": {
      "put": {
        "summary": "Update Tax",
        "operationId": "updateV3Tax",
        "tags": [
          "Taxes"
        ],
        "description": "Updates an existing tax rate.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tax id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateTaxRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3TaxResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — `Tax not found.`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — one entry per failed validation. English messages:\n- `Name can't be blank`\n- `Name is not available.` (another tax of the account has this name)\n- `Value can't be blank`\n- `Value is not a number`\n- `Value should be greater or equal to 0`\n- `Value must be less than or equal to 100`\n- `Region can't be empty` (unless `name` is `Isento`)\n- `Region the field must be one of the following values: AD|AE|...|PT-AC|PT-MA.`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Value must be less than or equal to 100"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — `Something went terribly wrong.` (e.g. an empty body, with no `tax` root and no top-level tax field). Top-level fields are wrapped into `tax` automatically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/taxes/1?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      },
      "delete": {
        "summary": "Delete Tax",
        "operationId": "deleteV3Tax",
        "tags": [
          "Taxes"
        ],
        "description": "Soft delete. The tax stops being listed and can no longer be used on new documents, but the row\nis kept so documents already issued with it still resolve its region and code (SAF-T). From then\non the tax answers `404`, and its name can be reused for a new tax. If it was the account's\ndefault tax, another tax becomes the default.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tax id"
          }
        ],
        "responses": {
          "204": {
            "description": "NO CONTENT"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — `Tax not found.`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. English messages:\n- `Can't delete this tax. There are items configured with this tax`\n- `Can't remove last tax, at least one tax needed for creating invoices`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/taxes/1?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/users/{id}": {
      "get": {
        "summary": "Get User",
        "operationId": "getV3User",
        "tags": [
          "Current User"
        ],
        "description": "Returns the current user. `id` must be the id of the caller.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "User id. Must be the caller's own id."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UserResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND. `id` is not the caller's own id (\"User not found.\"), also for other users of the same account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "User not found."
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/users/1?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "put": {
        "summary": "Update User",
        "operationId": "updateV3User",
        "tags": [
          "Current User"
        ],
        "description": "Updates the current account user's profile.\n\nThe email (and login) cannot be changed here. `user.email` / `user.login`\nmay be sent only with the current value; a different value rejects the\nwhole request with 422. Email changes go through\n`POST /api/v3/users/{id}/email_change`.\n\n`user.name` is saved as `first_name`. To change the password, send\n`actual_password` (current password), `password` and\n`password_confirmation`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "User id. Must be the caller's own id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateUserRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UserResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN. `id` is another user of the account (\"Request not allowed.\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Request not allowed."
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND. `id` is not a user of the account (\"User not found.\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "User not found."
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. Returned, among other validation errors, when `user.email` or `user.login` differs from the current value, when `user.actual_password` is wrong (\"Invalid current email/password combination.\"), or when `password` and `password_confirmation` differ (\"Password mismatch\").",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "error": {
                            "type": "string"
                          }
                        }
                      },
                      "example": [
                        {
                          "error": "Email changes must be requested through POST /users/:id/email_change."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR. Also returned for an empty body (no `user` root and no top-level user field; \"Something went terribly wrong.\"). Top-level user fields are wrapped into `user` automatically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/users/1?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/users/{id}/api_key": {
      "get": {
        "summary": "Get User Api Key",
        "operationId": "getV3UserApiKey",
        "tags": [
          "Current User"
        ],
        "description": "Returns the caller's API key for the current account. `id` must be the id of the caller.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "User id. Must be the caller's own id."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ApiKeyResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND. `id` is not the caller's own id (\"User not found.\"), also for other users of the same account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "User not found."
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/users/1/api_key?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Create User Api Key",
        "operationId": "createV3UserApiKey",
        "tags": [
          "Current User"
        ],
        "description": "Generates a new API key for the caller on the current account.\n\n**Warning:** this regenerates the key. If the caller already has an\nAPI key, it is replaced and the old one stops working immediately,\nincluding the key used to make this request.\n\nThe `id` path parameter is ignored: the call always acts on the\ncaller.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "User id. Ignored; the call acts on the caller."
          }
        ],
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ApiKeyResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/users/1/api_key?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      },
      "delete": {
        "summary": "Delete User Api Key",
        "operationId": "deleteV3UserApiKey",
        "tags": [
          "Current User"
        ],
        "description": "Removes the caller's API key on the current account, which disables\nAPI access for the caller on that account (including the key used to\nmake this request) until a new key is created.\n\nThe `id` path parameter is ignored: the call always acts on the\ncaller.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "User id. Ignored; the call acts on the caller."
          }
        ],
        "responses": {
          "204": {
            "description": "NO CONTENT"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/users/1/api_key?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/users/{id}/accounts": {
      "get": {
        "summary": "Get User Accounts",
        "operationId": "listV3UserAccounts",
        "tags": [
          "Current User"
        ],
        "description": "Returns the list of accounts the caller has access to. The `id` path parameter is ignored; the call always acts on the caller.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "User id. Ignored; the call acts on the caller."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UserAccountsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND. The caller has no (non-deleted) accounts (\"User does not have companies.\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/users/1/accounts?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/users/recover_password": {
      "post": {
        "summary": "Recover Password",
        "operationId": "recoverV3UserPassword",
        "tags": [
          "Current User"
        ],
        "description": "Sends a password reset link to the given user's email address. No authentication. Messages are in the language given by `language` (`pt`, `en` or `es`), Portuguese by default; the examples below are in English.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3RecoverPasswordRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3RecoverPasswordResponse"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND. No user has that email (\"We couldn't find a user with the email address you entered.\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "We couldn't find a user with the email address you entered."
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY.\n- `user.email` missing or blank: \"Enter your email address.\"\n- The user never finished signing up (no account was created): the\n  error carries `code: \"signup_unfinished\"`.\n",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "error": {
                            "type": "string"
                          },
                          "code": {
                            "type": "string",
                            "enum": [
                              "signup_unfinished"
                            ],
                            "description": "Only present when the user never finished signing up."
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "emailMissing": {
                    "summary": "Email missing",
                    "value": {
                      "errors": [
                        {
                          "error": "Enter your email address."
                        }
                      ]
                    }
                  },
                  "signupUnfinished": {
                    "summary": "Sign-up not finished",
                    "value": {
                      "errors": [
                        {
                          "error": "Your sign-up was not completed: the account has not been created yet. Sign up again with this email to finish creating your account.",
                          "code": "signup_unfinished"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR (\"Something went terribly wrong.\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/users/recover_password\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/users/reset_password": {
      "post": {
        "summary": "Reset Password",
        "operationId": "resetV3UserPassword",
        "tags": [
          "Current User"
        ],
        "description": "Resets a user's password using the reset code sent by the recover password endpoint. No authentication. Messages are in the language given by `language` (`pt`, `en` or `es`); otherwise in the language of the user's account, or Portuguese. The examples below are in English.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3ResetPasswordRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ResetPasswordResponse"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND. Unknown reset code (\"That is an invalid password reset code. Please check your code and try again.\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "That is an invalid password reset code. Please check your code and try again."
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY.\n- `user.reset_code` missing or blank: \"Enter your email address and\n  reset code sent by email.\"\n- `password` and `password_confirmation` differ (\"Password\n  mismatch\"), the password is too weak, or it equals the current\n  one (\"Password can't be identical to the current one\").\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Enter your email address and reset code sent by email."
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR (\"Something went terribly wrong.\").",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/users/reset_password\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/sequences/registered_series": {
      "get": {
        "summary": "Get Registered Series",
        "operationId": "getV3RegisteredSeries",
        "tags": [
          "Sequences"
        ],
        "description": "Returns a list of registered series names for the account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3RegisteredSeriesResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/sequences/registered_series?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/currencies": {
      "get": {
        "summary": "List Currencies",
        "operationId": "listV3Currencies",
        "tags": [
          "Currencies"
        ],
        "description": "Returns a list of all currencies.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CurrencyListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/currencies?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/currencies/rate/{from}/{to}": {
      "get": {
        "summary": "Get Exchange Rate",
        "operationId": "getV3CurrencyRate",
        "tags": [
          "Currencies"
        ],
        "description": "Retrieves the current exchange rate between two currencies, including provider information. If the exchange rate cannot be fetched (unknown code, or a code not in upper case), the response is still HTTP 200, with `success` set to `false` and no other field.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "from",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "EUR"
            },
            "description": "Source currency code (ISO 4217, upper case — the lookup is case-sensitive)."
          },
          {
            "name": "to",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "USD"
            },
            "description": "Target currency code (ISO 4217, upper case — the lookup is case-sensitive)."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS — `success` is `false` when no rate was found",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/V3CurrencyExchangeRateResponse"
                    },
                    {
                      "$ref": "#/components/schemas/V3CurrencyExchangeRateFailureResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/currencies/rate/EUR/USD?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/dashboard/active_clients": {
      "get": {
        "summary": "Get Active Clients",
        "operationId": "getV3DashboardActiveClients",
        "tags": [
          "Dashboard"
        ],
        "description": "Returns recurring and new clients per month for the last 12 months.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DashboardActiveClientsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/dashboard/active_clients?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/dashboard/clients_kpi": {
      "get": {
        "summary": "Get Clients KPI",
        "operationId": "getV3DashboardClientsKpi",
        "tags": [
          "Dashboard"
        ],
        "description": "Returns KPI metrics for clients over the last 12 months.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DashboardClientsKpiResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/dashboard/clients_kpi?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/dashboard/clients_dependency": {
      "get": {
        "summary": "Get Clients Dependency",
        "operationId": "getV3DashboardClientsDependency",
        "tags": [
          "Dashboard"
        ],
        "description": "Returns the revenue share segments per client for the account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DashboardClientsDependencyResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/dashboard/clients_dependency?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/dashboard/daily_invoicing": {
      "get": {
        "summary": "Get Daily Invoicing",
        "operationId": "getV3DashboardDailyInvoicing",
        "tags": [
          "Dashboard"
        ],
        "description": "Returns the daily invoicing totals for the account within an optional date range. Both dates default to the current month. A date that cannot be parsed is not an error; it silently falls back to its default.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2025-11-01"
            },
            "description": "Start date of the period. Defaults to the first day of the current month, also when the value cannot be parsed."
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2025-11-30"
            },
            "description": "End date of the period. Defaults to the last day of the current month, also when the value cannot be parsed."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DashboardDailyInvoicingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/dashboard/daily_invoicing?api_key=YOUR_API_KEY&start_date=2025-11-01&end_date=2025-11-30\""
          }
        ]
      }
    },
    "/api/v3/favorites": {
      "post": {
        "summary": "Create Favorite",
        "operationId": "createV3Favorite",
        "tags": [
          "Favorites"
        ],
        "description": "Creates a new favorite filter set for a user on a given tab.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateFavoriteRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3FavoriteCreateResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — `tab` missing (\"param is missing or the value is empty or invalid: tab\"). A missing `favorite` key does not give 422 (the body is wrapped into `favorite` automatically).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/favorites?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      }
    },
    "/api/v3/favorites/{uid}": {
      "get": {
        "summary": "Get Favorite",
        "operationId": "getV3Favorite",
        "tags": [
          "Favorites"
        ],
        "description": "Returns the filters of a specific favorite by uid.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Favorite uid"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3FavoriteDetailResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/favorites/bddeb153-0e80-4238-846f-546c0327f451?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "put": {
        "summary": "Rename Favorite",
        "operationId": "updateV3Favorite",
        "tags": [
          "Favorites"
        ],
        "description": "Renames an existing custom favorite and/or replaces its filters (`favorite.filters`).",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Favorite uid"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdateFavoriteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3FavoriteUpdateResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — \"No favorite was found with the provided uid\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — `tab` missing (\"param is missing or the value is empty or invalid: tab\"). A missing `favorite` key does not give 422 (the body is wrapped into `favorite` automatically).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — storage error, or \"A catastrophic error has occurred! So sorry!\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/favorites/bddeb153-0e80-4238-846f-546c0327f451?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      },
      "delete": {
        "summary": "Delete Favorite",
        "operationId": "deleteV3Favorite",
        "tags": [
          "Favorites"
        ],
        "description": "Deletes a custom favorite.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "uid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Favorite uid"
          }
        ],
        "responses": {
          "204": {
            "description": "NO CONTENT"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — \"No favorite was found with the provided uid\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — storage error, or \"A catastrophic error has occurred! So sorry!\"",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/favorites/bddeb153-0e80-4238-846f-546c0327f451?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/favorites/all": {
      "get": {
        "summary": "List All Favorites",
        "operationId": "listV3AllFavorites",
        "tags": [
          "Favorites"
        ],
        "description": "Returns a list of all user-created favorites for a given tab.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "tab",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "Invoices"
            },
            "description": "Current tab to list favorites for."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3FavoriteListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/favorites/all?api_key=YOUR_API_KEY&tab=Invoices\""
          }
        ]
      }
    },
    "/api/v3/favorites/default": {
      "get": {
        "summary": "List Default Favorites",
        "operationId": "listV3DefaultFavorites",
        "tags": [
          "Favorites"
        ],
        "description": "Returns a list of all default (system) favorites for a given tab.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "tab",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "Invoices"
            },
            "description": "Current tab to list favorites for."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3FavoriteListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/favorites/default?api_key=YOUR_API_KEY&tab=Invoices\""
          }
        ]
      }
    },
    "/api/v3/payment_services": {
      "get": {
        "summary": "List Payment Services",
        "operationId": "listV3PaymentServices",
        "tags": [
          "Payment Services"
        ],
        "description": "Returns all available payment services along with the one currently configured for the account, if any.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PaymentServiceListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/payment_services?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Create Payment Service",
        "operationId": "createV3PaymentService",
        "tags": [
          "Payment Services"
        ],
        "description": "Registers a payment service for the account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreatePaymentServiceRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PaymentServiceResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — top-level `id` missing (no JSON error body is guaranteed)"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — account already has a payment service configured (\"Account already has a payment service configured. Cancel and try again.\"), the service is disabled (\"Can't register a disabled payment service.\"), or registration failed validation (\"An error occured while registering the payment service.\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — also returned for an unknown `id` or a missing `payment_service` wrapper",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/payment_services?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"id\":1,\"payment_service\":{\"credentials\":{\"key\":\"value\"}}}'"
          }
        ]
      }
    },
    "/api/v3/payment_services/{id}": {
      "put": {
        "summary": "Update Payment Service",
        "operationId": "updateV3PaymentService",
        "tags": [
          "Payment Services"
        ],
        "description": "Updates the configuration of an existing payment service.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Payment service id"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3UpdatePaymentServiceRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PaymentServiceResponse"
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST — `payment_service` wrapper missing (no JSON error body is guaranteed)"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — `id` is not the account's current payment service (\"Can't update payment service that is not already configured.\"), a non-editable credential was changed (\"This field cannot be edited.\"), or the update failed validation (\"An error occured while updating the payment service.\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/payment_services/1?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      },
      "delete": {
        "summary": "Delete Payment Service",
        "operationId": "deleteV3PaymentService",
        "tags": [
          "Payment Services"
        ],
        "description": "Removes the payment service configuration from the account.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Payment service id"
          }
        ],
        "responses": {
          "204": {
            "description": "NO CONTENT"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — `id` is not the configured payment service (`Can't cancel a payment service that is not already configured`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — also returned when the account has no payment service configured and `id` is unknown (`Something went terribly wrong.`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/payment_services/1?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/payment_services/references": {
      "get": {
        "summary": "List Payment Service References",
        "operationId": "listV3PaymentServiceReferences",
        "tags": [
          "Payment Services"
        ],
        "description": "Returns a paginated list of payment references (e.g. Multibanco) generated through the account's configured payment service.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number for pagination.",
            "schema": {
              "type": "integer",
              "example": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Number of items per page.",
            "schema": {
              "type": "integer",
              "example": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PaymentServiceReferencesResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/payment_services/references?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/phone_calling_codes": {
      "get": {
        "summary": "List Phone Calling Codes",
        "operationId": "listV3PhoneCallingCodes",
        "tags": [
          "Phone Calling Codes"
        ],
        "description": "Returns a list of all phone country calling codes. This endpoint is public — no API key is needed. When an `api_key` is sent, the account language is used as the default response language.",
        "security": [],
        "parameters": [
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "Language of `translated_phone_code`. Unsupported values are ignored. Defaults to the account language when an `api_key` is sent, otherwise `en`.",
            "schema": {
              "type": "string",
              "enum": [
                "pt",
                "en",
                "es"
              ],
              "example": "pt"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3PhoneCallingCodeListResponse"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Something went wrong"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/phone_calling_codes?language=en\""
          }
        ]
      }
    },
    "/api/v3/reports/balance_per_client": {
      "get": {
        "summary": "Get Balance Per Client Report",
        "operationId": "getV3ReportBalancePerClient",
        "tags": [
          "Reports"
        ],
        "description": "Returns a paginated list of balances per client, with optional date-range, client, and tax filtering.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number for pagination, starting at 1. `0` or a negative value answers 500.",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1,
              "example": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Number of items per page. No maximum is enforced.",
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "example": 10
            }
          },
          {
            "name": "date_from",
            "in": "query",
            "required": false,
            "description": "Start date for filtering (format YYYY-MM-DD). Defaults to 1900-01-01 if not provided.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2025-01-01"
            }
          },
          {
            "name": "date_to",
            "in": "query",
            "required": false,
            "description": "End date for filtering (format YYYY-MM-DD). Defaults to today if not provided.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2025-12-31"
            }
          },
          {
            "name": "client_id",
            "in": "query",
            "required": false,
            "description": "Filter by client ID. Accepts a comma-separated list of ids (e.g. `123,456`).",
            "schema": {
              "type": "string",
              "example": "123,456"
            }
          },
          {
            "name": "with_taxes",
            "in": "query",
            "required": false,
            "description": "Include taxes in the report. Defaults to false.",
            "schema": {
              "type": "boolean",
              "default": false,
              "example": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BalancePerClientResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN — the account's plan does not include reports (\"Upgrade now\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/reports/balance_per_client?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/reports/balance_per_client/export": {
      "get": {
        "summary": "Export Balance Per Client Report",
        "operationId": "exportV3ReportBalancePerClient",
        "tags": [
          "Reports"
        ],
        "description": "Exports the full balance per client report as an XLSX file, using the same filters as the report endpoint. Results are not paginated — all matching rows are included. Generates the file, uploads it to S3, and returns a presigned download URL valid for about 7 days (`X-Amz-Expires=597600`).",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "date_from",
            "in": "query",
            "required": false,
            "description": "Start date for filtering (format YYYY-MM-DD). Defaults to 1900-01-01 if not provided.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2025-01-01"
            }
          },
          {
            "name": "date_to",
            "in": "query",
            "required": false,
            "description": "End date for filtering (format YYYY-MM-DD). Defaults to today if not provided.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2025-12-31"
            }
          },
          {
            "name": "client_id",
            "in": "query",
            "required": false,
            "description": "Filter by client ID. Accepts a comma-separated list of ids (e.g. `123,456`).",
            "schema": {
              "type": "string",
              "example": "123,456"
            }
          },
          {
            "name": "with_taxes",
            "in": "query",
            "required": false,
            "description": "Include taxes in amounts. Defaults to false.",
            "schema": {
              "type": "boolean",
              "default": false,
              "example": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS — presigned XLSX download URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BalancePerClientExportResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN — the account's plan does not include reports (\"Upgrade now\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/reports/balance_per_client/export?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/reports/balance_per_client/summary": {
      "get": {
        "summary": "Get Balance Per Client Report Summary",
        "operationId": "getV3ReportBalancePerClientSummary",
        "tags": [
          "Reports"
        ],
        "description": "Returns the aggregate summary of balances per client, using the same filters as the report endpoint.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "date_from",
            "in": "query",
            "required": false,
            "description": "Start date for filtering (format YYYY-MM-DD). Defaults to 1900-01-01 if not provided.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2025-01-01"
            }
          },
          {
            "name": "date_to",
            "in": "query",
            "required": false,
            "description": "End date for filtering (format YYYY-MM-DD). Defaults to today if not provided.",
            "schema": {
              "type": "string",
              "format": "date",
              "example": "2025-12-31"
            }
          },
          {
            "name": "client_id",
            "in": "query",
            "required": false,
            "description": "Filter by client ID. Accepts a comma-separated list of ids (e.g. `123,456`).",
            "schema": {
              "type": "string",
              "example": "123,456"
            }
          },
          {
            "name": "with_taxes",
            "in": "query",
            "required": false,
            "description": "Include taxes in the report. Defaults to false.",
            "schema": {
              "type": "boolean",
              "default": false,
              "example": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3BalancePerClientSummaryResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN — the account's plan does not include reports (\"Upgrade now\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/reports/balance_per_client/summary?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/saft/export.json": {
      "get": {
        "summary": "Generate SAF-T File",
        "operationId": "getV3SaftExport",
        "tags": [
          "SAF-T"
        ],
        "description": "Generates the SAF-T file for a specific period. The operation is asynchronous — the first response returns `202` while the file is being generated; keep requesting until you receive `200` with the download URL. If there are no documents to export in the selected period, returns `200` with a `message` instead of a `url`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "guides"
              ],
              "default": "all",
              "example": "all"
            },
            "description": "SAF-T type."
          },
          {
            "name": "period",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "year",
                "month",
                "week",
                "day"
              ],
              "default": "month",
              "example": "month"
            },
            "description": "The period for which to generate the SAF-T."
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 2015,
              "example": 2026
            },
            "description": "The year for which to generate the SAF-T, from 2015 to the current year (otherwise 422). Defaults to the current year."
          },
          {
            "name": "month",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 12,
              "example": 6
            },
            "description": "The month for which to generate the SAF-T, 1 to 12 (otherwise 422). Defaults to the current month."
          },
          {
            "name": "day",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "1"
            },
            "description": "Required when `period` is `week` or `day`; ignored for `year` and `month`. With `period=day` it is the exact day. With `period=week` it can be any day of the wanted week (Monday to Sunday); the week is cut at the month boundaries of `year`/`month`. Omitting it with `week` or `day` returns `500` (after the company-data check)."
          },
          {
            "name": "overwrite",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "example": false
            },
            "description": "Accepted for compatibility; it has no effect."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS — the link to download your SAF-T file",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SaftExportResponse"
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED — file generation started, keep requesting until `200`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SaftExportPendingResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED — invalid or missing API key, or the account is in trial\n(`SAF-T export is not available for trial accounts. Please subscribe to access this feature.`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                },
                "examples": {
                  "trial": {
                    "summary": "Trial account",
                    "value": {
                      "errors": [
                        {
                          "error": "SAF-T export is not available for trial accounts. Please subscribe to access this feature."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "CONFLICT — the company information required for the SAF-T is incomplete",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SaftExportConflictResponse"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — a query parameter has an invalid value",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Some parameters sent in the request were not valid."
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — also returned when `day` is missing with `period=week` or `period=day`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "example": {
                  "errors": [
                    {
                      "error": "Error generating SAF-T. Please try again."
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/saft/export.json?api_key=YOUR_API_KEY&period=month&year=2026&month=6\""
          }
        ]
      }
    },
    "/api/v3/tax_countries": {
      "get": {
        "summary": "List Tax Countries",
        "operationId": "listV3TaxCountries",
        "tags": [
          "Tax Countries"
        ],
        "description": "Returns a list of all tax countries.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "Language of `translated_name`. Unsupported values are ignored. Defaults to the account language, otherwise `en`.",
            "schema": {
              "type": "string",
              "enum": [
                "pt",
                "en",
                "es"
              ],
              "example": "pt"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3TaxCountryListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/tax_countries?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/digital_signatures/providers": {
      "get": {
        "summary": "List Digital Signature Providers",
        "operationId": "getV3DigitalSignatureProviders",
        "tags": [
          "Digital signatures"
        ],
        "description": "Gets the list of all available digital signature providers.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DigitalSignatureProviderListResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — e.g. the AMA (SAFE) authorization URL could not be obtained.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/providers?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/digital_signatures/accounts/providers": {
      "get": {
        "summary": "Get Account Digital Signature Provider",
        "operationId": "getV3DigitalSignatureAccountProvider",
        "tags": [
          "Digital signatures"
        ],
        "description": "Gets the customer's active digital signature provider. The body is the account provider object at the top level (no wrapper).",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DigitalSignatureAccountProviderObject"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — no stored signature credentials for the account, also when no provider is configured (\"Credentials are not found when we try set credentials\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — the provider authorization URL could not be obtained",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/providers?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Set Account Digital Signature Provider",
        "operationId": "createV3DigitalSignatureAccountProvider",
        "tags": [
          "Digital signatures"
        ],
        "description": "Sets the customer's digital signature provider.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateDigitalSignatureAccountProviderRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS — provider was added successfully to the account. The body is the linked provider itself, flat (no wrapper).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DigitalSignatureProviderObject"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — `provider_id` missing or unknown (bare string, e.g. \"Couldn't find DsProvider without an ID\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DigitalSignatureCredentialsErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — the provider rejected the credentials (\"Credentials are not valid\"), or the account provider failed validation (errors keyed by attribute, e.g. `consent_agreement` not `true` → \"can't be blank\", account already has a provider → `account` \"has already been taken\")",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/V3ServerError"
                    },
                    {
                      "$ref": "#/components/schemas/V3DigitalSignatureValidationErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "503": {
            "description": "SERVICE UNAVAILABLE — the provider did not answer in time (\"Signature provider is temporarily unavailable\"). Retry after the `Retry-After` delay.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 30
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/providers?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"provider_id\":1,\"client_id\":\"3b897ad6-cce4-4c54-a7e7-2bd00b83ab85\",\"client_secret\":\"ChvH5AUVhLNU\",\"consent_agreement\":true}'"
          }
        ]
      },
      "put": {
        "summary": "Update Account Digital Signature Provider",
        "operationId": "updateV3DigitalSignatureAccountProvider",
        "tags": [
          "Digital signatures"
        ],
        "description": "Updates the active customer's digital signature provider.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateDigitalSignatureAccountProviderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS — the body is the linked provider itself, flat (no wrapper).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DigitalSignatureProviderObject"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — `provider_id` missing or unknown, or no provider configured for this account (bare string)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DigitalSignatureCredentialsErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — the provider rejected the credentials (\"Credentials are not valid\"), or validation failed (errors keyed by attribute, e.g. `consent_agreement` not `true` → \"can't be blank\")",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/V3ServerError"
                    },
                    {
                      "$ref": "#/components/schemas/V3DigitalSignatureValidationErrorResponse"
                    }
                  ]
                }
              }
            }
          },
          "503": {
            "description": "SERVICE UNAVAILABLE — the provider did not answer in time (\"Signature provider is temporarily unavailable\"). Retry after the `Retry-After` delay.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 30
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/providers?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"provider_id\":1,\"client_id\":\"3b897ad6-cce4-4c54-a7e7-2bd00b83ab85\",\"client_secret\":\"ChvH5AUVhLNU\",\"consent_agreement\":true}'"
          }
        ]
      },
      "delete": {
        "summary": "Remove Account Digital Signature Provider",
        "operationId": "deleteV3DigitalSignatureAccountProvider",
        "tags": [
          "Digital signatures"
        ],
        "description": "Removes the account's digital signature provider and its credentials. Idempotent; answers 204 also when no provider is configured.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "204": {
            "description": "NO CONTENT — provider removed, or there was none."
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — e.g. cancelling the signature with the provider failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/providers?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/digital_signatures/accounts/credentials": {
      "get": {
        "summary": "Get Digital Signature Provider Credentials",
        "operationId": "getV3DigitalSignatureCredentials",
        "tags": [
          "Digital signatures"
        ],
        "description": "Gets the customer's digital signature provider credentials. The secret is never returned in clear.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DigitalSignatureCredentialsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — two shapes. No provider configured for this account → bare string (`{\"errors\":\"Couldn't find DsAccountProvider ...\"}`). Provider configured but no stored credentials → error list (\"Credentials are not found when we try set credentials\").",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/V3DigitalSignatureCredentialsErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/V3ServerError"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/credentials?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Set Digital Signature Provider Credentials",
        "operationId": "createV3DigitalSignatureCredentials",
        "tags": [
          "Digital signatures"
        ],
        "description": "Sets the customer's digital signature provider credentials. Requires an active digital signature provider to already be configured for the account (see the account providers endpoints).",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3DigitalSignatureCredentialsObject"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "NO CONTENT — credentials were checked with the provider and stored"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — no active digital signature provider is configured for this account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DigitalSignatureCredentialsErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — the provider rejected the credentials (\"Credentials are not valid\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — storing the credentials failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "503": {
            "description": "SERVICE UNAVAILABLE — the provider did not answer in time (\"Signature provider is temporarily unavailable\"). Retry after the `Retry-After` delay.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 30
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/credentials?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"client_id\":\"3b897ad6-cce4-4c54-a7e7-2bd00b83ab85\",\"client_secret\":\"ChvH5AUVhLNU\"}'"
          }
        ]
      },
      "put": {
        "summary": "Update Digital Signature Provider Credentials",
        "operationId": "updateV3DigitalSignatureCredentials",
        "tags": [
          "Digital signatures"
        ],
        "description": "Updates the customer's digital signature provider credentials. Requires an active digital signature provider to already be configured for the account (see the account providers endpoints).",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3DigitalSignatureCredentialsObject"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "NO CONTENT — credentials were checked with the provider and updated"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — two shapes. No provider configured for this account → bare string. No credentials stored yet (use POST) → error list (\"Credentials are not found when we try update\").",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/V3DigitalSignatureCredentialsErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/V3ServerError"
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — the provider rejected the credentials (\"Credentials are not valid\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "503": {
            "description": "SERVICE UNAVAILABLE — the provider did not answer in time (\"Signature provider is temporarily unavailable\"). Retry after the `Retry-After` delay.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 30
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/credentials?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"client_id\":\"3b897ad6-cce4-4c54-a7e7-2bd00b83ab85\",\"client_secret\":\"ChvH5AUVhLNU\"}'"
          }
        ]
      },
      "patch": {
        "summary": "Patch Digital Signature Provider Credentials",
        "operationId": "patchV3DigitalSignatureCredentials",
        "tags": [
          "Digital signatures"
        ],
        "description": "Updates the customer's digital signature provider credentials. Equivalent to `PUT` on this same path — the API accepts both verbs. Requires an active digital signature provider to already be configured for the account (see the account providers endpoints).",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3DigitalSignatureCredentialsObject"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS — credentials were updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DigitalSignatureCredentialsObject"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — no active digital signature provider is configured for this account. May return an empty body for this verb."
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PATCH \"https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/credentials?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{}'"
          }
        ]
      },
      "delete": {
        "summary": "Remove Digital Signature Provider Credentials",
        "operationId": "deleteV3DigitalSignatureCredentials",
        "tags": [
          "Digital signatures"
        ],
        "description": "Removes the customer's digital signature provider credentials.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "204": {
            "description": "NO CONTENT — credentials were removed successfully"
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — two shapes. No provider configured for this account → bare string. No stored credentials → error list (\"Credentials are not found when we try set credentials\").",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/V3DigitalSignatureCredentialsErrorResponse"
                    },
                    {
                      "$ref": "#/components/schemas/V3ServerError"
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — removing the credentials failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/accounts/credentials?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/digital_signature/info": {
      "get": {
        "summary": "Get Digital Signature Info",
        "operationId": "getV3DigitalSignatureInfo",
        "tags": [
          "Digital signatures"
        ],
        "description": "Returns the digital signature configuration data for the current account, including provider details, credentials, and status information. If no digital signature is configured, returns `\"NOT_CONFIGURED\"`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DigitalSignatureInfoResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/digital_signature/info?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/digital_signatures/document/{document_id}/status": {
      "get": {
        "summary": "Get Document Digital Signature Status",
        "operationId": "getV3DigitalSignatureDocumentStatus",
        "tags": [
          "Digital signatures"
        ],
        "description": "Returns the digital signature status information for a specific document, including whether it is signed and whether it should be signed.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "example": 12345
            },
            "description": "The unique identifier of the document."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DigitalSignatureDocumentStatusResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED (\"Authentication Error\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — document not found in your account (\"Document not found\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — error while checking the stored PDF (\"A catastrophic error has occurred! So sorry!\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — e.g. unknown document id; `errors` is the bare lookup error message (e.g. \"Couldn't find Invoice with 'id'=...\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DigitalSignatureCredentialsErrorResponse"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/document/12345/status?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/digital_signatures/document/{id}/sign": {
      "put": {
        "summary": "Sign Document",
        "operationId": "signV3DigitalSignatureDocument",
        "tags": [
          "Digital signatures"
        ],
        "description": "Triggers the digital signature process for a specific document by its ID. This will generate a new PDF for the document including the digital signature.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "example": 12345
            },
            "description": "The unique identifier of the document."
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS — PDF regeneration requested (legacy PDF service). Body is an empty object `{}`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "example": {}
                }
              }
            }
          },
          "202": {
            "description": "ACCEPTED — account uses PDF service v2; the signed PDF is produced asynchronously. Poll the document status endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3DigitalSignatureSignAcceptedResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — document not found (\"Document not found\")",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/digital_signatures/document/12345/sign?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v1/edi/{id}/cius-pt": {
      "get": {
        "summary": "Download CIUS-PT File",
        "operationId": "getV3DocumentCiusPt",
        "tags": [
          "EDI"
        ],
        "description": "Generates and downloads the CIUS-PT (electronic invoice) file for a document. The operation is asynchronous: while the file is being generated the response body is `{\"generating\": true}`; keep polling until the body contains `key` and `url`.\n\nBoth cases return HTTP `200` — unlike the SAF-T export and the PDF and QR code endpoints, this endpoint does **not** return `202` while generating. The only difference is which fields are present in the body.\n\nNote that this endpoint takes a bare document `id` with no document-type segment, so any document in the account can be addressed. Only `Invoice`, `InvoiceReceipt`, `SimplifiedInvoice`, `DebitNote` and `CreditNote` documents are eligible — VAT MOSS invoices are not, and return `406`. Draft documents also return `406`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS — `key` and `url` when the file is ready, `generating: true` while it is still being generated",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/V3CiusPtReadyResponse"
                    },
                    {
                      "$ref": "#/components/schemas/V3CiusPtProcessingResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED — account in trial (`Account is in trial. subscribe in order to have access to this feature`) or on a plan without CIUS-PT support (`Invalid plan error`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CiusPtUnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — no document with this id in the account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "406": {
            "description": "NOT ACCEPTABLE — document type not eligible for CIUS-PT, or the document is a draft",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CiusPtNotAcceptableError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — error generating the CIUS-PT file",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CiusPtGenerationError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — error uploading the generated file to storage (the body carries the exception message). A missing or invalid `api_key` is answered with a generic 500 (not 401) whose body may not follow the `errors` format shown here.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v1/edi/541674/cius-pt?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v1/edi/{id}/additional_fields": {
      "get": {
        "summary": "Get CIUS Additional Fields",
        "operationId": "getV3DocumentCiusAdditionalFields",
        "tags": [
          "EDI"
        ],
        "description": "Returns the CIUS/EDI additional fields (order and delivery references, accounting cost, delivery date) associated with a document. Every field is always present in the response; each one is `null` when no additional fields have been stored for the document yet.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CiusAdditionalFieldsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED — only when an `X-Account-Subdomain` header names a different account than the API key's. A missing or invalid `api_key` is not answered with 401 (see 500).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — no document with this id in the account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR. A missing or invalid `api_key` is answered with a generic 500 (not 401) whose body may not follow the `errors` format shown here.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v1/edi/541674/additional_fields?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Create or Update CIUS Additional Fields",
        "operationId": "createV3DocumentCiusAdditionalFields",
        "tags": [
          "EDI"
        ],
        "description": "Creates the document's CIUS/EDI additional fields, or updates them if they already exist — the same endpoint serves both cases. Returns `201` when the record is created and `200` when an existing record is updated.\n\nFields omitted from the payload keep their stored value, so this is a partial update rather than a replace.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3IdParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3CreateCiusAdditionalFieldsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS — existing additional fields updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CiusAdditionalFieldsResponse"
                }
              }
            }
          },
          "201": {
            "description": "CREATED — additional fields created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CiusAdditionalFieldsResponse"
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED — only when an `X-Account-Subdomain` header names a different account than the API key's. A missing or invalid `api_key` is not answered with 401 (see 500).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND — no document with this id in the account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3NotFoundError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY — `actual_delivery_date` is not a valid date",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3CiusAdditionalFieldsError"
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR — e.g. the `additional_fields` wrapper is missing (`param is missing or the value is empty or invalid: additional_fields`). A missing or invalid `api_key` is answered with a generic 500 (not 401) whose body may not follow the `errors` format shown here.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v1/edi/541674/additional_fields?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"additional_fields\":{\"order_reference\":\"PO-2026-0042\",\"actual_delivery_date\":\"2026-06-01\"}}'"
          }
        ]
      }
    },
    "/api/v3/accounts/social_security": {
      "get": {
        "summary": "Get Social Security Settings",
        "operationId": "getV3SocialSecurity",
        "tags": [
          "Social Security"
        ],
        "description": "Returns the account's Social Security settings, wrapped in a `social_security` key. Always `200`: when nothing is configured it returns the defaults with `niss: null`, which is how a client detects that the account is not set up yet. Requires the `administrator` or `contributor` role. Error messages follow the language of the account (pt, en or es), not the `Accept-Language` header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityResponse"
                },
                "examples": {
                  "not_set_up": {
                    "summary": "No settings yet (defaults)",
                    "value": {
                      "social_security": {
                        "niss": null,
                        "worker_type": "independente",
                        "regime": "services",
                        "exempt": false,
                        "special_profile": "none"
                      }
                    }
                  },
                  "configured": {
                    "summary": "Settings exist",
                    "value": {
                      "social_security": {
                        "niss": "12345678902",
                        "worker_type": "eni",
                        "regime": "services",
                        "exempt": false,
                        "special_profile": "none"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN. The role is not allowed, the account is blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityForbiddenError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "post": {
        "summary": "Create Social Security Settings",
        "operationId": "createV3SocialSecurity",
        "tags": [
          "Social Security"
        ],
        "description": "Creates the account's Social Security settings. Send the fields wrapped in a `social_security` key. `niss` is required. It is normalised (spaces, `-`, `.` and `/` are stripped), must have 11 digits, start with `1` or `2` and have a valid check digit. If settings already exist the call answers `422`; use `PUT` instead. Do not send `null` for `worker_type`, `regime`, `exempt` or `special_profile` (the API answers `500`). `regime`, `exempt` and `special_profile` are stored and returned but no calculation uses them; only `worker_type` changes the contribution rate. Requires the `administrator` or `contributor` role. Error messages follow the language of the account (pt, en or es), not the `Accept-Language` header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3SocialSecurityCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityResponse"
                },
                "examples": {
                  "settings": {
                    "value": {
                      "social_security": {
                        "niss": "12345678902",
                        "worker_type": "eni",
                        "regime": "services",
                        "exempt": false,
                        "special_profile": "none"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST. Returned for an empty body, `{}`, `\"social_security\": null` or `\"social_security\": {}` (body `status`/`error`), and for malformed JSON (body `errors[].error`, \"Invalid request body or parameters.\"). Only the wrapped form `{\"social_security\": {...}}` is documented; top-level fields without the wrapper are accepted today but not supported.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/V3SocialSecurityBadRequestError"
                    },
                    {
                      "$ref": "#/components/schemas/V3SocialSecurityError"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN. The role is not allowed, the account is blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityForbiddenError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. Settings already exist, or `niss` or an enum value is invalid. Only the first error is returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityError"
                },
                "examples": {
                  "already_exists": {
                    "value": {
                      "errors": [
                        {
                          "error": "A NISS is already set for this account. Use update instead."
                        }
                      ]
                    }
                  },
                  "blank_niss": {
                    "value": {
                      "errors": [
                        {
                          "error": "The NISS can't be blank."
                        }
                      ]
                    }
                  },
                  "invalid_niss": {
                    "value": {
                      "errors": [
                        {
                          "error": "The NISS is not valid."
                        }
                      ]
                    }
                  },
                  "invalid_worker_type": {
                    "value": {
                      "errors": [
                        {
                          "error": "worker_type must be either 'independente' or 'eni'."
                        }
                      ]
                    }
                  },
                  "invalid_regime": {
                    "value": {
                      "errors": [
                        {
                          "error": "regime must be 'services', 'goods', or 'mixed'."
                        }
                      ]
                    }
                  },
                  "invalid_special_profile": {
                    "value": {
                      "errors": [
                        {
                          "error": "special_profile must be 'none', 'organized_accounting', 'accumulation', or 'own_fund'."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR. `null` was sent for `worker_type`, `regime`, `exempt` or `special_profile` (the columns are not nullable), or `social_security` is not an object. Validate the input; do not retry unchanged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityInternalError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"social_security\":{\"niss\":\"123-456-789-02\",\"worker_type\":\"eni\"}}'"
          }
        ]
      },
      "put": {
        "summary": "Update Social Security Settings",
        "operationId": "updateV3SocialSecurity",
        "tags": [
          "Social Security"
        ],
        "description": "Updates the account's Social Security settings. `PATCH` is routed to the same action and behaves identically. Send only the fields to change, wrapped in a `social_security` key; the response always returns all five. Answers `404` when no settings exist yet; use `POST` first. `niss` is validated only when it changes, so a stored invalid NISS does not block updating other fields. Do not send `null` for `worker_type`, `regime`, `exempt` or `special_profile` (the API answers `500`). Requires the `administrator` or `contributor` role. Error messages follow the language of the account (pt, en or es), not the `Accept-Language` header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3SocialSecurityUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityResponse"
                },
                "examples": {
                  "settings": {
                    "value": {
                      "social_security": {
                        "niss": "12345678902",
                        "worker_type": "independente",
                        "regime": "services",
                        "exempt": false,
                        "special_profile": "none"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST. Returned for an empty body, `{}`, `\"social_security\": null` or `\"social_security\": {}` (body `status`/`error`), and for malformed JSON (body `errors[].error`, \"Invalid request body or parameters.\"). Only the wrapped form `{\"social_security\": {...}}` is documented; top-level fields without the wrapper are accepted today but not supported.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/V3SocialSecurityBadRequestError"
                    },
                    {
                      "$ref": "#/components/schemas/V3SocialSecurityError"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN. The role is not allowed, the account is blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND. No settings exist yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityError"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "errors": [
                        {
                          "error": "No NISS is set for this account yet."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. `niss` or an enum value is invalid. Only the first error is returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityError"
                },
                "examples": {
                  "blank_niss": {
                    "value": {
                      "errors": [
                        {
                          "error": "The NISS can't be blank."
                        }
                      ]
                    }
                  },
                  "invalid_niss": {
                    "value": {
                      "errors": [
                        {
                          "error": "The NISS is not valid."
                        }
                      ]
                    }
                  },
                  "invalid_worker_type": {
                    "value": {
                      "errors": [
                        {
                          "error": "worker_type must be either 'independente' or 'eni'."
                        }
                      ]
                    }
                  },
                  "invalid_regime": {
                    "value": {
                      "errors": [
                        {
                          "error": "regime must be 'services', 'goods', or 'mixed'."
                        }
                      ]
                    }
                  },
                  "invalid_special_profile": {
                    "value": {
                      "errors": [
                        {
                          "error": "special_profile must be 'none', 'organized_accounting', 'accumulation', or 'own_fund'."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR. `null` was sent for `worker_type`, `regime`, `exempt` or `special_profile` (the columns are not nullable), or `social_security` is not an object. Validate the input; do not retry unchanged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityInternalError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"social_security\":{\"worker_type\":\"independente\"}}'"
          }
        ]
      },
      "delete": {
        "summary": "Delete Social Security Settings",
        "operationId": "deleteV3SocialSecurity",
        "tags": [
          "Social Security"
        ],
        "description": "Deletes the account's Social Security settings and also deletes every quarterly self-report recorded for the account. Idempotent: always `200` with `{\"success\": true}`, whether or not anything existed. The quarterly declaration endpoints answer `422` again afterwards. Cached quarters keep their `submitted_at`; it shows again if settings are re-created. Requires the `administrator` or `contributor` role. Error messages follow the language of the account (pt, en or es), not the `Accept-Language` header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityDeleteResponse"
                },
                "examples": {
                  "deleted": {
                    "value": {
                      "success": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN. The role is not allowed, the account is blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityForbiddenError"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X DELETE \"https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security?api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/api/v3/accounts/social_security_reports": {
      "post": {
        "summary": "Create Social Security Report",
        "operationId": "createV3SocialSecurityReport",
        "tags": [
          "Social Security"
        ],
        "description": "Records that the account declared a quarter in Segurança Social Direta, and what it was charged. It is a personal tracking record; nothing is sent anywhere. Send the fields wrapped in a `social_security_report` key; `year` (`1583` to `9999`, except `year` `9999` with `quarter` `4` and `reported_at` set, which answers `500` and saves nothing; the API does not validate it and a value outside the range may answer `500`) and `quarter` (`1` to `4`) are required and identify the report (there is no id): at most one per account, year and quarter. `estimated_monthly_payment` and `monthly_payment` accept `0` to `9999999999.99` and are returned as decimal strings rounded to 2 places, in the shortest form but always with at least one decimal digit (`\"70.0\"`, `\"55.1\"`, `\"53.52\"`). Setting `reported_at` also sets `submitted_at` of that quarter on the quarterly declaration endpoints. The account must already have a NISS (`POST /api/v3/accounts/social_security`), otherwise the call answers `422`. A report cannot be deleted on its own: there is no `DELETE`; reports are removed only by `DELETE /api/v3/accounts/social_security`, which deletes all of them. Requires the `administrator` or `contributor` role. Error messages follow the language of the account (pt, en or es), not the `Accept-Language` header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3SocialSecurityReportCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "SUCCESS. Echoes all five fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityReportResponse"
                },
                "examples": {
                  "report": {
                    "value": {
                      "social_security_report": {
                        "year": 2026,
                        "quarter": 2,
                        "reported_at": "2026-07-15T20:08:03+01:00",
                        "estimated_monthly_payment": "53.53",
                        "monthly_payment": "55.1"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST. Malformed JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityError"
                },
                "examples": {
                  "invalid_body": {
                    "value": {
                      "errors": [
                        {
                          "error": "Invalid request body or parameters."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN. The role is not allowed, the account is blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityForbiddenError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. The account has no NISS configured (checked first), or a report for that year and quarter already exists (use `PUT`), or validation failed. Validation messages are the framework's own, can list more than one error (for example a missing `quarter` lists two), and are shown here in English.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityError"
                },
                "examples": {
                  "not_configured": {
                    "value": {
                      "errors": [
                        {
                          "error": "This account hasn't set up Social Security tracking yet. Set a NISS first."
                        }
                      ]
                    }
                  },
                  "already_exists": {
                    "value": {
                      "errors": [
                        {
                          "error": "Quarter has already been taken"
                        }
                      ]
                    }
                  },
                  "missing_year": {
                    "value": {
                      "errors": [
                        {
                          "error": "Year can't be blank"
                        }
                      ]
                    }
                  },
                  "missing_quarter": {
                    "value": {
                      "errors": [
                        {
                          "error": "Quarter can't be blank"
                        },
                        {
                          "error": "Quarter is not included in the list"
                        }
                      ]
                    }
                  },
                  "quarter_out_of_range": {
                    "value": {
                      "errors": [
                        {
                          "error": "Quarter is not included in the list"
                        }
                      ]
                    }
                  },
                  "negative_amount": {
                    "value": {
                      "errors": [
                        {
                          "error": "Monthly payment must be greater than or equal to 0"
                        }
                      ]
                    }
                  },
                  "oversized_amount": {
                    "value": {
                      "errors": [
                        {
                          "error": "Estimated monthly payment must be less than or equal to 9999999999.99"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR. Unexpected failure (reported to the InvoiceXpress team); nothing is saved, no half-created report is left behind. Also the answer for `year` `9999` with `quarter` `4` when `reported_at` is set (nothing is saved), and for an empty body, `{}`, `\"social_security_report\": null` or `\"social_security_report\": {}`: it is not a `400`. Only the wrapped form is documented; top-level fields without the wrapper are accepted today but not supported. Validate the input; do not retry unchanged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "examples": {
                  "unexpected": {
                    "value": {
                      "errors": [
                        {
                          "error": "Something went terribly wrong."
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X POST \"https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security_reports?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"social_security_report\":{\"year\":2026,\"quarter\":2,\"reported_at\":\"2026-07-15T19:08:03Z\",\"estimated_monthly_payment\":53.53,\"monthly_payment\":55.10}}'"
          }
        ]
      }
    },
    "/api/v3/accounts/social_security_reports/{year}/{quarter}": {
      "get": {
        "summary": "Get Social Security Report",
        "operationId": "getV3SocialSecurityReport",
        "tags": [
          "Social Security"
        ],
        "description": "Returns the quarterly self-report for `year` and `quarter`, wrapped in a `social_security_report` key. `422` is checked before `404`: without a NISS the answer is `422` even for a quarter that never had a report. With a NISS, `404` means no report exists for that quarter (the client can show a create form); it is also the answer when a URL segment is not purely digits (for example `/2026abc/2`). Requires the `administrator` or `contributor` role. Error messages follow the language of the account (pt, en or es), not the `Accept-Language` header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3SocialSecurityYearParam"
          },
          {
            "$ref": "#/components/parameters/V3SocialSecurityQuarterParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityReportResponse"
                },
                "examples": {
                  "report": {
                    "value": {
                      "social_security_report": {
                        "year": 2026,
                        "quarter": 2,
                        "reported_at": "2026-07-15T20:08:03+01:00",
                        "estimated_monthly_payment": "53.53",
                        "monthly_payment": "55.1"
                      }
                    }
                  },
                  "not_yet_declared": {
                    "summary": "Report without a declaration date or payments",
                    "value": {
                      "social_security_report": {
                        "year": 2026,
                        "quarter": 3,
                        "reported_at": null,
                        "estimated_monthly_payment": null,
                        "monthly_payment": null
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN. The role is not allowed, the account is blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND. The account has a NISS but no report exists for that year and quarter, or a URL segment is not purely digits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityError"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "errors": [
                        {
                          "error": "No report was found for this quarter yet."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. The account has no NISS configured. Create the settings with `POST /api/v3/accounts/social_security` first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityError"
                },
                "examples": {
                  "not_configured": {
                    "value": {
                      "errors": [
                        {
                          "error": "This account hasn't set up Social Security tracking yet. Set a NISS first."
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security_reports/2026/2?api_key=YOUR_API_KEY\""
          }
        ]
      },
      "put": {
        "summary": "Update Social Security Report",
        "operationId": "updateV3SocialSecurityReport",
        "tags": [
          "Social Security"
        ],
        "description": "Updates the quarterly self-report for `year` and `quarter`. `PATCH` is routed to the same action and behaves identically. Send only the fields to change, wrapped in a `social_security_report` key; the response always returns all five. `year` and `quarter` in the body are silently ignored, the URL identifies the report; there is no way to move a report to another quarter, and no `DELETE` (reports are removed only by `DELETE /api/v3/accounts/social_security`). `reported_at` and `submitted_at` of that quarter on the quarterly declaration endpoints are synced when a report is created or updated (deleting the settings does not clear `submitted_at`): setting or changing `reported_at` sets `submitted_at` to it, `null` clears `submitted_at`, and a change to only `estimated_monthly_payment` or `monthly_payment` leaves it untouched. Exception: for `year` `9999` with `quarter` `4`, setting `reported_at` answers `500` and saves nothing. `422` (no NISS) is checked before `404` (no report for that quarter, or a URL segment that is not purely digits). Requires the `administrator` or `contributor` role. Error messages follow the language of the account (pt, en or es), not the `Accept-Language` header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.",
        "parameters": [
          {
            "$ref": "#/components/parameters/V3SocialSecurityYearParam"
          },
          {
            "$ref": "#/components/parameters/V3SocialSecurityQuarterParam"
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/V3SocialSecurityReportUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SUCCESS. Returns all five fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityReportResponse"
                },
                "examples": {
                  "updated": {
                    "value": {
                      "social_security_report": {
                        "year": 2026,
                        "quarter": 2,
                        "reported_at": "2026-08-01T11:00:00+01:00",
                        "estimated_monthly_payment": "53.53",
                        "monthly_payment": "60.46"
                      }
                    }
                  },
                  "reported_at_cleared": {
                    "value": {
                      "social_security_report": {
                        "year": 2026,
                        "quarter": 2,
                        "reported_at": null,
                        "estimated_monthly_payment": "53.53",
                        "monthly_payment": "60.46"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "BAD REQUEST. Malformed JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityError"
                },
                "examples": {
                  "invalid_body": {
                    "value": {
                      "errors": [
                        {
                          "error": "Invalid request body or parameters."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN. The role is not allowed, the account is blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityForbiddenError"
                }
              }
            }
          },
          "404": {
            "description": "NOT FOUND. The account has a NISS but no report exists for that year and quarter, or a URL segment is not purely digits. Use `POST` to create it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityError"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "errors": [
                        {
                          "error": "No report was found for this quarter yet."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. The account has no NISS configured (checked first), or an amount is negative or above `9999999999.99`. Validation messages are the framework's own and are shown here in English.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityError"
                },
                "examples": {
                  "not_configured": {
                    "value": {
                      "errors": [
                        {
                          "error": "This account hasn't set up Social Security tracking yet. Set a NISS first."
                        }
                      ]
                    }
                  },
                  "negative_amount": {
                    "value": {
                      "errors": [
                        {
                          "error": "Monthly payment must be greater than or equal to 0"
                        }
                      ]
                    }
                  },
                  "oversized_amount": {
                    "value": {
                      "errors": [
                        {
                          "error": "Estimated monthly payment must be less than or equal to 9999999999.99"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR. Unexpected failure (reported to the InvoiceXpress team); the update is rolled back. Also the answer for `year` `9999` with `quarter` `4` when `reported_at` is set (nothing is saved), and for an empty body, `{}`, `\"social_security_report\": null` or `\"social_security_report\": {}`: it is not a `400`. Only the wrapped form is documented; top-level fields without the wrapper are accepted today but not supported. Validate the input; do not retry unchanged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "examples": {
                  "unexpected": {
                    "value": {
                      "errors": [
                        {
                          "error": "Something went terribly wrong."
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X PUT \"https://api-v3.app.invoicexpress.com/api/v3/accounts/social_security_reports/2026/2?api_key=YOUR_API_KEY\" -H \"Content-Type: application/json\" --data '{\"social_security_report\":{\"reported_at\":\"2026-08-01T10:00:00Z\",\"monthly_payment\":60.46}}'"
          }
        ]
      }
    },
    "/services/v1/social_security/quarterly_declaration": {
      "get": {
        "summary": "Get Social Security Quarterly Declaration",
        "operationId": "getV3SocialSecurityQuarterlyDeclaration",
        "tags": [
          "Social Security"
        ],
        "description": "Returns the totals of one quarter, calculated from the account's invoices. Needs a NISS: answers `422` until the settings exist. Served under `/services/v1/`, not `/api/v3/`, on the same host. `year` and `quarter` are optional and never produce a `422`. Year and quarter rules: `year` and `quarter` are read as integers like Ruby `to_i`: leading digits are used, and a single underscore between digits is accepted (`2026abc` and `2_026` are `2026`; `2__026` is `2`; `abc` is `0`). If either is missing, if `year` is not positive, or if `quarter` is not `1` to `4`, both fall back to the last completed quarter (the previous quarter; from January to March, quarter 4 of the previous year) and the answer is `200`, so check `year` and `quarter` in the response. Supported range: `year` `1583` to `9999` with `quarter` `1` to `4`, except `year=9999&quarter=4`, which answers `500`. Outside the supported range, results are not guaranteed and may answer `500` (for example a `year` of `10000` or more with a valid `quarter`, or some years before `1583`). A `year` or `quarter` sent as an array or hash (`year[]=1`, `quarter[]=1`) answers `500`. Counts `Invoice`, `SimplifiedInvoice` and `InvoiceReceipt` documents with status `sent`, `settled` or `second_copy` dated inside the quarter, using the gross amount before VAT (`total_before_taxes`). Credit and debit notes, plain receipts, drafts, cancelled and deleted documents, estimates and guides are not counted. Money totals are decimal strings. Every `estimated_*` field is an estimate; `total_amount` is the figure to declare. `niss` and `worker_type` are read live from the current settings. Requires the `administrator` or `contributor` role. Error messages follow the language of the account (pt, en or es), not the `Accept-Language` header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social. The current open month is always calculated live; a closed month is cached and recalculated in the background when a document dated in it is finalised, cancelled or deleted, so the previous total can still be served for a short while. Recalculation is debounced to one run per month every 30 seconds: a change made within 30 seconds of an earlier one in the same month is not queued, and the cached total may stay out of date until a later change in that month. Documents with no `type` (legacy) are counted as well.",
        "parameters": [
          {
            "name": "year",
            "in": "query",
            "required": false,
            "description": "Year of the quarter, read as an integer like Ruby `to_i` (`2026abc` and `2_026` are `2026`; `abc` is `0`). If it is missing or not positive, or `quarter` is missing or not `1` to `4`, both parameters fall back to the last completed quarter (`200`). Supported range: `1583` to `9999`, except `year=9999&quarter=4` (`500`). Outside it, results are not guaranteed and may answer `500`. An array or hash (`year[]=1`) answers `500`.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "example": 2026
            }
          },
          {
            "name": "quarter",
            "in": "query",
            "required": false,
            "description": "Quarter, `1` to `4`, read as an integer like Ruby `to_i` (a single underscore between digits is accepted). If it is missing or any other value, both parameters fall back to the last completed quarter (`200`, no `422`). An array or hash (`quarter[]=1`) answers `500`.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 4,
              "example": 2
            }
          },
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityQuarterlyDeclaration"
                },
                "examples": {
                  "with_invoicing": {
                    "summary": "Quarter with invoicing (illustrative amounts)",
                    "value": {
                      "year": 2026,
                      "quarter": 2,
                      "start_date": "2026-04-01",
                      "end_date": "2026-06-30",
                      "total_amount": "1250.5",
                      "services_amount": "1000.5",
                      "goods_amount": "250.0",
                      "document_count": 4,
                      "monthly_breakdown": [
                        {
                          "month": 4,
                          "total_amount": "0.0",
                          "services_amount": "0.0",
                          "goods_amount": "0.0",
                          "document_count": 0
                        },
                        {
                          "month": 5,
                          "total_amount": "500.0",
                          "services_amount": "400.0",
                          "goods_amount": "100.0",
                          "document_count": 2
                        },
                        {
                          "month": 6,
                          "total_amount": "750.5",
                          "services_amount": "600.5",
                          "goods_amount": "150.0",
                          "document_count": 2
                        }
                      ],
                      "niss": "12345678902",
                      "worker_type": "independente",
                      "contribution_year": 2026,
                      "ias": "537.13",
                      "monthly_base_cap": "6445.56",
                      "estimated_relevant_income": 750.35,
                      "estimated_monthly_payment": 53.52,
                      "submitted_at": "2026-07-15T19:08:03.000Z"
                    }
                  },
                  "no_invoicing": {
                    "summary": "Quarter with no invoicing (the 20.00 minimum still applies)",
                    "value": {
                      "year": 2026,
                      "quarter": 2,
                      "start_date": "2026-04-01",
                      "end_date": "2026-06-30",
                      "total_amount": "0.0",
                      "services_amount": "0.0",
                      "goods_amount": "0.0",
                      "document_count": 0,
                      "monthly_breakdown": [
                        {
                          "month": 4,
                          "total_amount": "0.0",
                          "services_amount": "0.0",
                          "goods_amount": "0.0",
                          "document_count": 0
                        },
                        {
                          "month": 5,
                          "total_amount": "0.0",
                          "services_amount": "0.0",
                          "goods_amount": "0.0",
                          "document_count": 0
                        },
                        {
                          "month": 6,
                          "total_amount": "0.0",
                          "services_amount": "0.0",
                          "goods_amount": "0.0",
                          "document_count": 0
                        }
                      ],
                      "niss": "12345678902",
                      "worker_type": "independente",
                      "contribution_year": 2026,
                      "ias": "537.13",
                      "monthly_base_cap": "6445.56",
                      "estimated_relevant_income": 0,
                      "estimated_monthly_payment": 20,
                      "submitted_at": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN. The role is not allowed, the account is blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityForbiddenError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. The account has no NISS configured. Create the settings with `POST /api/v3/accounts/social_security` first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityError"
                },
                "examples": {
                  "not_configured": {
                    "value": {
                      "errors": [
                        {
                          "error": "This account hasn't set up Social Security tracking yet. Set a NISS first."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR. Unexpected failure while calculating (reported to the InvoiceXpress team). Safe to call again: a transient failure may succeed on a later try. Also the answer for `year=9999&quarter=4`, for some `year` values outside the supported range (`1583` to `9999`, for example `10000` or more with a valid `quarter`), and for a `year` or `quarter` sent as an array or hash; repeating those requests gives the same answer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "examples": {
                  "unexpected": {
                    "value": {
                      "errors": [
                        {
                          "error": "Something went terribly wrong."
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/services/v1/social_security/quarterly_declaration?year=2026&quarter=2&api_key=YOUR_API_KEY\""
          }
        ]
      }
    },
    "/services/v1/social_security/quarterly_declarations": {
      "get": {
        "summary": "List Social Security Quarterly Declarations",
        "operationId": "listV3SocialSecurityQuarterlyDeclarations",
        "tags": [
          "Social Security"
        ],
        "description": "Returns the declaration history, grouped by year, newest year first, with the quarters of each year newest first. Takes no query parameters other than `api_key` and ignores any that are sent. `niss` and `worker_type` are read live and appear once per year; each quarter object has the fields of the single declaration minus `year`, `niss` and `worker_type`. Needs a NISS: answers `422` until the settings exist. Served under `/services/v1/`, not `/api/v3/`, on the same host. Which quarters are listed, as a union: every quarter of the current year, including open and future ones (zeros when nothing is invoiced yet); every quarter the account invoiced in since 1 January two years before the current year (for example, since 1 January 2024 in 2026); every quarter that already has cached data, from any year, so history does not drop off. Each listed quarter is re-aggregated over its 3 months, so a total is never partial. A quarter with no invoicing still shows `estimated_monthly_payment: 20.0`, the monthly minimum. Money totals are decimal strings. Every `estimated_*` field is an estimate; `total_amount` is the figure to declare. Requires the `administrator` or `contributor` role. Error messages follow the language of the account (pt, en or es), not the `Accept-Language` header. JSON only. This feature only calculates and records; it submits nothing to Segurança Social.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiKeyParam"
          }
        ],
        "responses": {
          "200": {
            "description": "SUCCESS",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/V3SocialSecurityYearGroup"
                  }
                },
                "examples": {
                  "history": {
                    "summary": "Current year (all 4 quarters) and a past year that was invoiced",
                    "value": [
                      {
                        "year": 2026,
                        "quarters": [
                          {
                            "quarter": 4,
                            "start_date": "2026-10-01",
                            "end_date": "2026-12-31",
                            "total_amount": "6.0",
                            "services_amount": "6.0",
                            "goods_amount": "0.0",
                            "document_count": 2,
                            "monthly_breakdown": [
                              {
                                "month": 10,
                                "total_amount": "6.0",
                                "services_amount": "6.0",
                                "goods_amount": "0.0",
                                "document_count": 2
                              },
                              {
                                "month": 11,
                                "total_amount": "0.0",
                                "services_amount": "0.0",
                                "goods_amount": "0.0",
                                "document_count": 0
                              },
                              {
                                "month": 12,
                                "total_amount": "0.0",
                                "services_amount": "0.0",
                                "goods_amount": "0.0",
                                "document_count": 0
                              }
                            ],
                            "contribution_year": 2027,
                            "ias": "537.13",
                            "monthly_base_cap": "6445.56",
                            "estimated_relevant_income": 4.2,
                            "estimated_monthly_payment": 20,
                            "submitted_at": null
                          },
                          {
                            "quarter": 3,
                            "start_date": "2026-07-01",
                            "end_date": "2026-09-30",
                            "total_amount": "20.0",
                            "services_amount": "20.0",
                            "goods_amount": "0.0",
                            "document_count": 2,
                            "monthly_breakdown": [
                              {
                                "month": 7,
                                "total_amount": "0.0",
                                "services_amount": "0.0",
                                "goods_amount": "0.0",
                                "document_count": 0
                              },
                              {
                                "month": 8,
                                "total_amount": "0.0",
                                "services_amount": "0.0",
                                "goods_amount": "0.0",
                                "document_count": 0
                              },
                              {
                                "month": 9,
                                "total_amount": "20.0",
                                "services_amount": "20.0",
                                "goods_amount": "0.0",
                                "document_count": 2
                              }
                            ],
                            "contribution_year": 2026,
                            "ias": "537.13",
                            "monthly_base_cap": "6445.56",
                            "estimated_relevant_income": 14,
                            "estimated_monthly_payment": 20,
                            "submitted_at": null
                          },
                          {
                            "quarter": 2,
                            "start_date": "2026-04-01",
                            "end_date": "2026-06-30",
                            "total_amount": "0.0",
                            "services_amount": "0.0",
                            "goods_amount": "0.0",
                            "document_count": 0,
                            "monthly_breakdown": [
                              {
                                "month": 4,
                                "total_amount": "0.0",
                                "services_amount": "0.0",
                                "goods_amount": "0.0",
                                "document_count": 0
                              },
                              {
                                "month": 5,
                                "total_amount": "0.0",
                                "services_amount": "0.0",
                                "goods_amount": "0.0",
                                "document_count": 0
                              },
                              {
                                "month": 6,
                                "total_amount": "0.0",
                                "services_amount": "0.0",
                                "goods_amount": "0.0",
                                "document_count": 0
                              }
                            ],
                            "contribution_year": 2026,
                            "ias": "537.13",
                            "monthly_base_cap": "6445.56",
                            "estimated_relevant_income": 0,
                            "estimated_monthly_payment": 20,
                            "submitted_at": null
                          },
                          {
                            "quarter": 1,
                            "start_date": "2026-01-01",
                            "end_date": "2026-03-31",
                            "total_amount": "10.0",
                            "services_amount": "10.0",
                            "goods_amount": "0.0",
                            "document_count": 1,
                            "monthly_breakdown": [
                              {
                                "month": 1,
                                "total_amount": "0.0",
                                "services_amount": "0.0",
                                "goods_amount": "0.0",
                                "document_count": 0
                              },
                              {
                                "month": 2,
                                "total_amount": "10.0",
                                "services_amount": "10.0",
                                "goods_amount": "0.0",
                                "document_count": 1
                              },
                              {
                                "month": 3,
                                "total_amount": "0.0",
                                "services_amount": "0.0",
                                "goods_amount": "0.0",
                                "document_count": 0
                              }
                            ],
                            "contribution_year": 2026,
                            "ias": "537.13",
                            "monthly_base_cap": "6445.56",
                            "estimated_relevant_income": 7,
                            "estimated_monthly_payment": 20,
                            "submitted_at": null
                          }
                        ],
                        "niss": "12345678902",
                        "worker_type": "independente"
                      },
                      {
                        "year": 2025,
                        "quarters": [
                          {
                            "quarter": 3,
                            "start_date": "2025-07-01",
                            "end_date": "2025-09-30",
                            "total_amount": "110.0",
                            "services_amount": "110.0",
                            "goods_amount": "0.0",
                            "document_count": 11,
                            "monthly_breakdown": [
                              {
                                "month": 7,
                                "total_amount": "0.0",
                                "services_amount": "0.0",
                                "goods_amount": "0.0",
                                "document_count": 0
                              },
                              {
                                "month": 8,
                                "total_amount": "0.0",
                                "services_amount": "0.0",
                                "goods_amount": "0.0",
                                "document_count": 0
                              },
                              {
                                "month": 9,
                                "total_amount": "110.0",
                                "services_amount": "110.0",
                                "goods_amount": "0.0",
                                "document_count": 11
                              }
                            ],
                            "contribution_year": 2025,
                            "ias": "522.5",
                            "monthly_base_cap": "6270.0",
                            "estimated_relevant_income": 77,
                            "estimated_monthly_payment": 20,
                            "submitted_at": null
                          }
                        ],
                        "niss": "12345678902",
                        "worker_type": "independente"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "ACCESS DENIED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3UnauthorizedError"
                }
              }
            }
          },
          "403": {
            "description": "FORBIDDEN. The role is not allowed, the account is blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityForbiddenError"
                }
              }
            }
          },
          "422": {
            "description": "UNPROCESSABLE ENTITY. The account has no NISS configured. Create the settings with `POST /api/v3/accounts/social_security` first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3SocialSecurityError"
                },
                "examples": {
                  "not_configured": {
                    "value": {
                      "errors": [
                        {
                          "error": "This account hasn't set up Social Security tracking yet. Set a NISS first."
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "INTERNAL SERVER ERROR. Unexpected failure while calculating (reported to the InvoiceXpress team). Safe to call again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V3ServerError"
                },
                "examples": {
                  "unexpected": {
                    "value": {
                      "errors": [
                        {
                          "error": "Something went terribly wrong."
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "cURL",
            "source": "curl -X GET \"https://api-v3.app.invoicexpress.com/services/v1/social_security/quarterly_declarations?api_key=YOUR_API_KEY\""
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "query",
        "name": "api_key"
      }
    },
    "parameters": {
      "ApiKeyParam": {
        "name": "api_key",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string",
          "example": "YOUR_API_KEY"
        },
        "description": "Your API Key."
      },
      "DocumentTypeInvoiceParam": {
        "name": "invoices-type",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "enum": [
            "invoices",
            "invoice_receipts",
            "simplified_invoices",
            "credit_notes",
            "debit_notes"
          ]
        },
        "description": "The type of the invoice document."
      },
      "DocumentTypeGuideParam": {
        "name": "guides-type",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "enum": [
            "shippings",
            "transports",
            "devolutions"
          ]
        },
        "description": "The type of the guide document."
      },
      "V3DocumentTokenParam": {
        "name": "token",
        "in": "path",
        "required": true,
        "description": "The unique identifier (token) of the document.",
        "schema": {
          "type": "string",
          "example": "abc123token"
        }
      },
      "V3DocumentTypeInvoiceOrReceiptParam": {
        "name": "invoices-type",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "enum": [
            "invoices",
            "invoice_receipts",
            "simplified_invoices",
            "credit_notes",
            "debit_notes",
            "receipts"
          ]
        },
        "description": "The type of the invoice document. `receipts` (payment receipts) is accepted here; receipts have no create, update, clone or `/new` (those operations use DocumentTypeInvoiceParam)."
      },
      "V3PdfAttachmentQueryParam": {
        "name": "attachment",
        "in": "query",
        "required": false,
        "description": "When `true`, the returned URL serves the PDF as a download instead of inline display. Ignored by the legacy PDF service.",
        "schema": {
          "type": "boolean",
          "default": false
        }
      },
      "V3InvoicesQueryParamObject": {
        "name": "queryParams",
        "in": "query",
        "style": "form",
        "explode": true,
        "description": "Click to expand filter and pagination options.",
        "schema": {
          "$ref": "#/components/schemas/V3InvoicesQueryParams"
        }
      },
      "V3GuidesQueryParamObject": {
        "name": "queryParams",
        "in": "query",
        "style": "form",
        "explode": true,
        "description": "Click to expand filter and pagination options.",
        "schema": {
          "$ref": "#/components/schemas/V3GuidesQueryParams"
        }
      },
      "V3IdParam": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The document ID.",
        "schema": {
          "type": "integer",
          "example": 541674
        }
      },
      "V3SocialSecurityYearParam": {
        "name": "year",
        "in": "path",
        "required": true,
        "description": "Year of the quarterly self-report, digits only (for example `2026`). A segment that is not purely digits (such as `2026abc`) answers `404`, as does a year with no report.",
        "schema": {
          "type": "integer",
          "example": 2026
        }
      },
      "V3SocialSecurityQuarterParam": {
        "name": "quarter",
        "in": "path",
        "required": true,
        "description": "Quarter of the self-report, `1` to `4`, digits only. A segment that is not purely digits answers `404`, as does a quarter with no report (including `0` and `5` or more).",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 4,
          "example": 2
        }
      },
      "V3DocumentIdPathParam": {
        "name": "document_id",
        "in": "path",
        "required": true,
        "description": "The unique identifier of the document.",
        "schema": {
          "type": "integer",
          "example": 541674
        }
      },
      "V3CommentIdParam": {
        "name": "comment_id",
        "in": "path",
        "required": true,
        "description": "ID of the comment to delete.",
        "schema": {
          "type": "integer",
          "example": 1
        }
      },
      "V3DocumentTypeEstimateParam": {
        "name": "estimate_type",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "enum": [
            "quotes",
            "proformas",
            "fees_notes"
          ]
        },
        "description": "Type of estimate document (quotes, proformas, fees_notes)."
      },
      "V3EstimatesQueryParamObject": {
        "name": "queryParams",
        "in": "query",
        "style": "form",
        "explode": true,
        "description": "Click to expand filter and pagination options.",
        "schema": {
          "$ref": "#/components/schemas/V3EstimatesQueryParams"
        }
      },
      "V3PageQueryParam": {
        "name": "page",
        "in": "query",
        "required": false,
        "description": "Page number, starting at 1.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1,
          "example": 1
        }
      },
      "V3PerPageQueryParam": {
        "name": "per_page",
        "in": "query",
        "required": false,
        "description": "Number of entries per page. `items_per_page` and `page_items` are accepted as aliases.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 10,
          "example": 10
        }
      },
      "V3SortOrderQueryParam": {
        "name": "sort_order",
        "in": "query",
        "required": false,
        "description": "Sort direction.",
        "schema": {
          "type": "string",
          "enum": [
            "ASC",
            "DESC"
          ],
          "default": "ASC",
          "example": "DESC"
        }
      }
    },
    "schemas": {
      "V3DocumentResponse": {
        "type": "object",
        "properties": {
          "invoice": {
            "type": "object",
            "description": "Wrapper key matches the singular of the requested invoice\ntype (invoice, invoice_receipt, simplified_invoice, credit_note,\ndebit_note, or receipt).\n\nFor the `receipt` wrapper (payment receipts) the shape differs:\n`items` are the payments the receipt covers, each\n`{document_type, document_sequence_number, total, paid}` (e.g.\n`{\"document_type\": \"Invoice\", \"document_sequence_number\": \"2026/12\",\n\"total\": 123.0, \"paid\": 123.0}`) instead of product lines;\n`account.bank_data` and `auto_add_related_document` are not returned.",
            "properties": {
              "id": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Null in preview/transform contexts before the document is actually created.",
                "example": 264663413
              },
              "status": {
                "type": "string",
                "example": "draft"
              },
              "cancel_reason": {
                "type": "string",
                "description": "No enforced length limit; stored as a text column (maps to cancel_message).",
                "example": "document was duplicated"
              },
              "archived": {
                "type": "boolean",
                "example": false
              },
              "type": {
                "type": "string",
                "example": "Invoice"
              },
              "sequence_number": {
                "type": "string",
                "example": "draft"
              },
              "inverted_sequence_number": {
                "type": "string",
                "example": "draft"
              },
              "sequence_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": 5259451
              },
              "atcud": {
                "type": "string",
                "example": "N/A"
              },
              "saft_hash": {
                "type": "string",
                "description": "Only present once the document has been finalized — absent while it is still a draft.",
                "example": "FoIq"
              },
              "tax_exemption": {
                "type": "string",
                "example": "M01",
                "maxLength": 255,
                "description": "255-character database column default (column `tax_exemption_code`); effectively an enum of AT exemption codes."
              },
              "date": {
                "type": "string",
                "format": "date",
                "example": "2026-07-27"
              },
              "due_date": {
                "type": "string",
                "format": "date",
                "example": "2026-08-27"
              },
              "reference": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 255,
                "example": null
              },
              "observations": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "No enforced length limit; stored as a text column.",
                "example": null
              },
              "token": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Null in preview/transform contexts before the document is actually created.",
                "example": "2646634130360dcbca24d2d9509add7c92ccb1d7ab970ce6d"
              },
              "permalink": {
                "type": "string",
                "example": "https://web.invoicexpress.com/documents/2646634130360dcbca24d2d9509add7c92ccb1d7ab970ce6d?language=pt"
              },
              "retention": {
                "type": "number",
                "example": 0
              },
              "global_discount": {
                "$ref": "#/components/schemas/V3DocumentGlobalDiscount"
              },
              "owner_invoice_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": null
              },
              "raw_owner_invoice": {
                "$ref": "#/components/schemas/V3DocumentRawOwnerInvoice"
              },
              "currency": {
                "$ref": "#/components/schemas/V3DocumentCurrency"
              },
              "auto_add_related_document": {
                "type": "boolean",
                "example": false
              },
              "qr_code": {
                "$ref": "#/components/schemas/V3DocumentQrCodeField"
              },
              "digital_signed": {
                "$ref": "#/components/schemas/V3DocumentDigitalSignedField"
              },
              "include_payment_reference": {
                "$ref": "#/components/schemas/V3DocumentIncludePaymentReferenceField"
              },
              "account": {
                "type": "object",
                "properties": {
                  "organization_name": {
                    "type": "string",
                    "example": "invoicexpress"
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "detail": {
                        "type": "string",
                        "example": "Avenida Duque D'Avila, Saldanha"
                      },
                      "postal_code": {
                        "type": "string",
                        "example": "1500-555"
                      },
                      "city": {
                        "type": "string",
                        "example": "Lisbon"
                      },
                      "country": {
                        "type": "string",
                        "example": "Portugal"
                      },
                      "translated_country": {
                        "type": "string",
                        "description": "Country name in the request language.",
                        "example": "Portugal"
                      }
                    }
                  },
                  "email": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "info@mycompany.com"
                  },
                  "phone": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": null
                  },
                  "phone_country_code": {
                    "$ref": "#/components/schemas/V3DocumentPhoneCountryCode"
                  },
                  "phone_indicative_printed": {
                    "$ref": "#/components/schemas/V3DocumentPhoneIndicativePrinted"
                  },
                  "website": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": null
                  },
                  "footer": {
                    "$ref": "#/components/schemas/V3DocumentAccountFooter"
                  },
                  "fiscal_id": {
                    "type": "string",
                    "example": "999999990"
                  },
                  "logo": {
                    "type": "string",
                    "example": ""
                  },
                  "bank_data": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "example": "IBAN"
                        },
                        "value": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "example": null
                        }
                      }
                    }
                  }
                }
              },
              "client": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer",
                    "example": 196600840
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 100,
                    "example": "John Doe"
                  },
                  "email": {
                    "type": "string",
                    "maxLength": 254,
                    "example": "john@example.com"
                  },
                  "phone": {
                    "type": "string",
                    "description": "Empty string when unset.",
                    "example": "210000000"
                  },
                  "phone_country_code": {
                    "$ref": "#/components/schemas/V3DocumentPhoneCountryCode"
                  },
                  "mobile": {
                    "type": "string",
                    "description": "Empty string when unset.",
                    "example": "910000000"
                  },
                  "mobile_country_code": {
                    "$ref": "#/components/schemas/V3DocumentPhoneCountryCode"
                  },
                  "fiscal_id": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "255-character limit is the database column default, not an explicit validation.",
                    "example": "987654321"
                  },
                  "country": {
                    "type": "string",
                    "example": ""
                  },
                  "translated_country": {
                    "type": "string",
                    "description": "Client's fiscal country name in the request language.",
                    "example": "Portugal"
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "detail": {
                        "type": "string",
                        "description": "No enforced length limit; stored as a text column.",
                        "example": "456 Client Street"
                      },
                      "postal_code": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "255-character limit is the database column default, not an explicit validation.",
                        "example": "2000-002"
                      },
                      "city": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "255-character limit is the database column default, not an explicit validation.",
                        "example": "Porto"
                      },
                      "address_country": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "255-character limit is the database column default, not an explicit validation.",
                        "example": "PT"
                      }
                    }
                  }
                }
              },
              "items": {
                "type": "array",
                "description": "Product lines. For the `receipt` wrapper, the payments the receipt covers (`document_type`, `document_sequence_number`, `total`, `paid`) — see the wrapper description.",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "example": 484102115
                    },
                    "name": {
                      "type": "string",
                      "example": "Product Name",
                      "maxLength": 60,
                      "description": "Maximum 60 characters. Longer values are rejected with 422 (\"Code for the item is too long\")."
                    },
                    "description": {
                      "type": "string",
                      "example": "Product description",
                      "maxLength": 200,
                      "description": "Maximum 200 characters and at most 20 lines. Longer values are rejected with 422."
                    },
                    "unit_price": {
                      "type": "number",
                      "example": 100
                    },
                    "unit": {
                      "type": "string",
                      "description": "Must be one of a fixed set of supported unit values, not a length-limited free-text field.",
                      "example": "piece"
                    },
                    "quantity": {
                      "type": "number",
                      "example": 2
                    },
                    "tax": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "example": 756700
                        },
                        "name": {
                          "type": "string",
                          "maxLength": 255,
                          "description": "255-character limit is the database column default; only presence and uniqueness are validated.",
                          "example": "IVA23"
                        },
                        "value": {
                          "type": "number",
                          "example": 23
                        }
                      }
                    },
                    "discount": {
                      "type": "number",
                      "example": 10
                    },
                    "subtotal": {
                      "type": "number",
                      "example": 180
                    },
                    "tax_amount": {
                      "type": "number",
                      "example": 41.4
                    },
                    "discount_amount": {
                      "type": "number",
                      "example": 20
                    },
                    "total": {
                      "type": "number",
                      "example": 221.4
                    },
                    "retention": {
                      "type": "number",
                      "example": 0
                    }
                  }
                }
              },
              "summary": {
                "type": "object",
                "properties": {
                  "sum": {
                    "type": "number",
                    "example": 200
                  },
                  "discount": {
                    "type": "number",
                    "example": 20
                  },
                  "before_taxes": {
                    "type": "number",
                    "example": 180
                  },
                  "taxes": {
                    "type": "number",
                    "example": 41.4
                  },
                  "total": {
                    "type": "number",
                    "example": 221.4
                  },
                  "currency": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "example": "Euro"
                      },
                      "code": {
                        "type": "string",
                        "example": "EUR"
                      },
                      "symbol": {
                        "type": "string",
                        "example": "€"
                      }
                    }
                  },
                  "retention": {
                    "type": "number",
                    "example": 0
                  },
                  "pay_progress": {
                    "type": "number",
                    "example": 0
                  },
                  "to_pay": {
                    "type": "number",
                    "example": 221.4
                  },
                  "total_paid": {
                    "type": "number",
                    "example": 0
                  },
                  "taxes_breakdown": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "category": {
                          "type": "string",
                          "example": "IVA23"
                        },
                        "items_value": {
                          "type": "number",
                          "example": 180
                        },
                        "tax_value": {
                          "type": "number",
                          "example": 41.4
                        }
                      }
                    }
                  },
                  "total_currency_rate": {
                    "type": "number",
                    "example": 0
                  },
                  "rate": {
                    "type": "number",
                    "example": 1
                  }
                }
              },
              "mb_reference": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "entity": {
                    "type": "string",
                    "example": "12345"
                  },
                  "value": {
                    "type": "number",
                    "example": 221.4
                  },
                  "reference": {
                    "type": "string",
                    "example": "123 456 789"
                  }
                }
              }
            }
          }
        }
      },
      "V3InvoiceListResponse": {
        "type": "object",
        "properties": {
          "invoices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 541674
                },
                "sequence_number": {
                  "type": "string",
                  "example": "serie_name/4"
                },
                "sequence": {
                  "type": "string",
                  "example": "serie_name"
                },
                "document_number": {
                  "type": "string",
                  "example": "4"
                },
                "type": {
                  "type": "string",
                  "example": "VatMossCreditNote"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "draft",
                    "sent",
                    "settled",
                    "canceled",
                    "second_copy"
                  ],
                  "description": "Raw stored status. A finalized document is `sent` here, while show, create/update and change-state return it as `final`.",
                  "example": "canceled"
                },
                "archived": {
                  "type": "boolean",
                  "example": false
                },
                "client_name": {
                  "type": "string",
                  "example": "John Doe"
                },
                "reference": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "maxLength": 255,
                  "example": "PO-1234",
                  "description": "The document's free-text reference, the same value the `reference` filter searches. `null` when the document has none."
                },
                "date": {
                  "type": "string",
                  "example": "2023-01-03 00:00:00 +0000"
                },
                "due_date": {
                  "type": "string",
                  "example": "2023-01-03 00:00:00 +0000"
                },
                "total": {
                  "type": "number",
                  "example": 6.15
                },
                "total_before_taxes": {
                  "type": "number",
                  "example": 5
                },
                "final_date": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "2023-01-03 18:03:13 +0000"
                },
                "token": {
                  "type": "string",
                  "example": "541674bbfcdd182143fe2747524df08ab1367ef8255010"
                },
                "legacy_invoice_receipt_config": {
                  "type": [
                    "boolean",
                    "null"
                  ],
                  "example": false
                }
              }
            }
          },
          "totals": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "example": 44
              },
              "pages": {
                "type": "integer",
                "example": 5
              },
              "statuses": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "canceled"
                ]
              },
              "total_corrections": {
                "type": "number",
                "example": 0
              },
              "total_corrections_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_drafts": {
                "type": "number",
                "example": 0
              },
              "total_drafts_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_canceled": {
                "type": "number",
                "example": 3516.96
              },
              "total_canceled_with_taxes": {
                "type": "number",
                "example": 4325.87
              },
              "total_due": {
                "type": "number",
                "example": 0
              },
              "total_due_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_overdue": {
                "type": "number",
                "example": 0
              },
              "total_overdue_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_paid_before_taxes": {
                "type": "number",
                "example": 0
              },
              "total_paid_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_before_taxes": {
                "type": "number",
                "example": 0
              },
              "total_taxes": {
                "type": "number",
                "example": 0
              },
              "total": {
                "type": "number",
                "example": 0
              }
            }
          }
        }
      },
      "V3CreateInvoiceRequest": {
        "type": "object",
        "description": "The wrapper key matches the singular of the invoice type used in the path (invoice, invoice_receipt, simplified_invoice, credit_note, or debit_note) — shown here as \"invoice\". Keys not listed here are dropped by the server's parameter allowlist.",
        "properties": {
          "proprietary_uid": {
            "type": "string",
            "description": "Your own idempotency identifier for the document. Accepted here at the top level or inside the wrapper; a repeated value returns the document already created with it instead of creating a new one.",
            "example": "order-10045"
          },
          "invoice": {
            "type": "object",
            "required": [
              "date",
              "items"
            ],
            "properties": {
              "date": {
                "type": "string",
                "format": "date",
                "example": "2024-01-15"
              },
              "due_date": {
                "type": "string",
                "format": "date",
                "description": "Defaults to `date` when omitted or blank.",
                "example": "2024-02-15"
              },
              "reference": {
                "type": "string",
                "maxLength": 255,
                "example": "PO-1234"
              },
              "observations": {
                "type": "string",
                "description": "No enforced length limit; stored as a text column.",
                "example": "Payment terms: 30 days"
              },
              "sequence_id": {
                "type": "integer",
                "description": "Id of the sequence (series) to issue the document in. The account's default sequence is used when omitted.",
                "example": 5259451
              },
              "manual_sequence_number": {
                "type": "string",
                "maxLength": 255,
                "example": "001"
              },
              "tax_exemption": {
                "type": "string",
                "description": "AT tax exemption code (e.g. `M01`). `M00` clears a previously set exemption. Ignored when the account does not use tax exemption reasons or the code is unknown.",
                "example": "M01"
              },
              "tax_exemption_code": {
                "type": "string",
                "description": "Stored exemption code column; prefer `tax_exemption`.",
                "example": "M01"
              },
              "tax_exemption_reason": {
                "type": "string",
                "description": "Alias of `tax_exemption`, used only when `tax_exemption` is blank.",
                "example": "M01"
              },
              "retention": {
                "type": "number",
                "description": "Withholding tax rate (percentage). Only applied when it matches an active retention base; any other value is ignored.",
                "example": 25
              },
              "global_discount": {
                "type": [
                  "object",
                  "null"
                ],
                "description": "Document-level discount. Send `null` (or a value of 0) to remove an existing discount; omit the key to leave it unchanged.",
                "properties": {
                  "value_type": {
                    "type": "string",
                    "enum": [
                      "percentage",
                      "absolute"
                    ],
                    "example": "percentage"
                  },
                  "value": {
                    "type": "number",
                    "example": 10
                  }
                }
              },
              "currency_code": {
                "type": "string",
                "description": "Currency code (e.g. `USD`). Only applied when the account's plan includes multi-currency; unknown codes are ignored.",
                "example": "USD"
              },
              "rate": {
                "type": "number",
                "description": "Exchange rate to the account currency.",
                "default": 1,
                "example": 1.08
              },
              "owner_invoice_id": {
                "type": "integer",
                "description": "Id of the invoice this credit/debit note corrects.",
                "example": 541673
              },
              "raw_owner_invoice": {
                "description": "Reference to an original document issued outside InvoiceXpress, for a credit/debit note with no `owner_invoice_id`. Either a string `\"<TYPE> <SERIE>/<NUMBER>\"` (max 60 characters) or an object with the three parts.",
                "oneOf": [
                  {
                    "type": "string",
                    "maxLength": 60,
                    "example": "FT 2026/253"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "document_type": {
                        "type": "string",
                        "example": "FT"
                      },
                      "document_serie": {
                        "type": "string",
                        "example": "2026"
                      },
                      "document_number": {
                        "type": "string",
                        "example": "253"
                      }
                    }
                  }
                ]
              },
              "client_id": {
                "type": "integer",
                "description": "Id of an existing client. Alternative to `client.id`.",
                "example": 456
              },
              "mb_reference": {
                "type": "boolean",
                "description": "Generate a Multibanco payment reference for the document.",
                "example": false
              },
              "auto_add_related_document": {
                "type": "boolean",
                "description": "Overwritten by the server. Set to `false` unless `mb_reference` is true; with `mb_reference` true and the account's \"auto-send invoice from estimate\" setting on, it is forced to `true`.",
                "example": false
              },
              "proprietary_uid": {
                "type": "string",
                "description": "Same as the top-level `proprietary_uid`.",
                "example": "order-10045"
              },
              "client": {
                "type": "object",
                "description": "Optional. When omitted, the document is issued to Consumidor Final (credit and debit notes take the client of the invoice in `owner_invoice_id`).",
                "properties": {
                  "id": {
                    "type": "integer",
                    "description": "If provided and it matches an existing client on the account, that client is used and name/email/fiscal_id/address are ignored; otherwise name is used to find or create the client.",
                    "example": 456
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 100,
                    "example": "John Doe"
                  },
                  "email": {
                    "type": "string",
                    "maxLength": 254,
                    "example": "john@example.com"
                  },
                  "fiscal_id": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "255-character limit is the database column default, not an explicit validation.",
                    "example": "987654321"
                  },
                  "address": {
                    "type": "string",
                    "description": "Street address as a flat string (not a nested object). No enforced length limit; stored as a text column.",
                    "example": "456 Client Street"
                  },
                  "postal_code": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "255-character limit is the database column default, not an explicit validation.",
                    "example": "2000-002"
                  },
                  "city": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "255-character limit is the database column default, not an explicit validation.",
                    "example": "Porto"
                  },
                  "country": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "Fiscal country of the client. 255-character limit is the database column default, not an explicit validation.",
                    "example": "Portugal"
                  },
                  "address_country": {
                    "type": "string",
                    "description": "Country of the postal address, when different from the fiscal country; takes priority over `country` for the address.",
                    "example": "Portugal"
                  }
                }
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "example": "Product Name",
                      "maxLength": 60,
                      "description": "Maximum 60 characters. Longer values are rejected with 422 (\"Code for the item is too long\")."
                    },
                    "description": {
                      "type": "string",
                      "example": "Product description",
                      "maxLength": 200,
                      "description": "Maximum 200 characters and at most 20 lines. Longer values are rejected with 422."
                    },
                    "unit_price": {
                      "type": "number",
                      "example": 100
                    },
                    "unit": {
                      "type": "string",
                      "description": "Must be one of a fixed set of supported unit values, not a length-limited free-text field.",
                      "example": "piece"
                    },
                    "quantity": {
                      "type": "string",
                      "example": "2.00"
                    },
                    "tax": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "example": 1
                        },
                        "name": {
                          "type": "string",
                          "maxLength": 255,
                          "description": "255-character limit is the database column default; only presence and uniqueness are validated.",
                          "example": "IVA23"
                        },
                        "value": {
                          "type": "number",
                          "example": 23
                        }
                      }
                    },
                    "discount": {
                      "type": "number",
                      "example": 10
                    },
                    "subtotal": {
                      "type": "number",
                      "example": 180
                    },
                    "tax_amount": {
                      "type": "number",
                      "example": 41.4
                    },
                    "discount_amount": {
                      "type": "number",
                      "example": 20
                    },
                    "total": {
                      "type": "number",
                      "example": 221.4
                    },
                    "retention": {
                      "type": "number",
                      "example": 0
                    }
                  }
                }
              }
            }
          }
        }
      },
      "V3CreateDocumentError": {
        "type": "object",
        "description": "Validation failure when creating a document. Each entry carries one message; model validation errors use the model's full message text.",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "No invoice element provided"
              },
              {
                "error": "No items element provided"
              }
            ]
          }
        }
      },
      "V3InvoiceResponse": {
        "type": "object",
        "properties": {
          "invoice": {
            "type": "object",
            "description": "Wrapper key matches the singular of the requested invoice type (invoice, invoice_receipt, simplified_invoice, credit_note, or debit_note).",
            "properties": {
              "id": {
                "type": "integer",
                "example": 541674
              },
              "status": {
                "type": "string",
                "enum": [
                  "draft",
                  "final",
                  "settled",
                  "canceled",
                  "second_copy"
                ],
                "description": "A finalized document is returned as `final` (the list endpoint returns the same document as `sent`).",
                "example": "final"
              },
              "cancel_reason": {
                "type": "string",
                "description": "No enforced length limit; stored as a text column (maps to cancel_message).",
                "example": "document was duplicated"
              },
              "archived": {
                "type": "boolean",
                "example": false
              },
              "type": {
                "type": "string",
                "example": "Invoice"
              },
              "sequence_number": {
                "type": "string",
                "example": "2024/001"
              },
              "inverted_sequence_number": {
                "type": "string",
                "example": "001/2024"
              },
              "sequence_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": 123
              },
              "owner_invoice_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": 541673
              },
              "atcud": {
                "type": "string",
                "example": "ATCUD123456"
              },
              "saft_hash": {
                "type": "string",
                "description": "Only present once the document has been finalized — absent while it is still a draft.",
                "example": "1234"
              },
              "tax_exemption": {
                "type": "string",
                "example": "M01",
                "maxLength": 255,
                "description": "255-character database column default (column `tax_exemption_code`); effectively an enum of AT exemption codes."
              },
              "date": {
                "type": "string",
                "format": "date",
                "example": "2024-01-15"
              },
              "due_date": {
                "type": "string",
                "format": "date",
                "example": "2024-02-15"
              },
              "reference": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 255,
                "example": "REF001"
              },
              "observations": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "No enforced length limit; stored as a text column.",
                "example": "Payment terms: 30 days"
              },
              "token": {
                "type": "string",
                "example": "541674bbfcdd182143fe2747524df08ab1367ef8255010"
              },
              "permalink": {
                "type": "string",
                "example": "https://web.invoicexpress.com/documents/541674bbfcdd182143fe2747524df08ab1367ef8255010?language=pt"
              },
              "retention": {
                "type": "number",
                "example": 0
              },
              "global_discount": {
                "$ref": "#/components/schemas/V3DocumentGlobalDiscount"
              },
              "raw_owner_invoice": {
                "$ref": "#/components/schemas/V3DocumentRawOwnerInvoice"
              },
              "currency": {
                "$ref": "#/components/schemas/V3DocumentCurrency"
              },
              "auto_add_related_document": {
                "type": "boolean",
                "example": false
              },
              "qr_code": {
                "$ref": "#/components/schemas/V3DocumentQrCodeField"
              },
              "digital_signed": {
                "$ref": "#/components/schemas/V3DocumentDigitalSignedField"
              },
              "include_payment_reference": {
                "$ref": "#/components/schemas/V3DocumentIncludePaymentReferenceField"
              },
              "account": {
                "type": "object",
                "properties": {
                  "organization_name": {
                    "type": "string",
                    "example": "My Company Ltd"
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "detail": {
                        "type": "string",
                        "example": "123 Main Street"
                      },
                      "postal_code": {
                        "type": "string",
                        "example": "1000-001"
                      },
                      "city": {
                        "type": "string",
                        "example": "Lisbon"
                      },
                      "country": {
                        "type": "string",
                        "example": "Portugal"
                      },
                      "translated_country": {
                        "type": "string",
                        "description": "Country name in the request language.",
                        "example": "Portugal"
                      }
                    }
                  },
                  "email": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "info@mycompany.com"
                  },
                  "phone": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": null
                  },
                  "phone_country_code": {
                    "$ref": "#/components/schemas/V3DocumentPhoneCountryCode"
                  },
                  "phone_indicative_printed": {
                    "$ref": "#/components/schemas/V3DocumentPhoneIndicativePrinted"
                  },
                  "website": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": null
                  },
                  "footer": {
                    "$ref": "#/components/schemas/V3DocumentAccountFooter"
                  },
                  "fiscal_id": {
                    "type": "string",
                    "example": "123456789"
                  },
                  "logo": {
                    "type": "string",
                    "example": "https://example.com/logo.png"
                  },
                  "bank_data": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "example": "IBAN"
                        },
                        "value": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "example": "PT50123456789012345678901"
                        }
                      }
                    }
                  }
                }
              },
              "client": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer",
                    "example": 456
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 100,
                    "example": "John Doe"
                  },
                  "email": {
                    "type": "string",
                    "maxLength": 254,
                    "example": "john@example.com"
                  },
                  "phone": {
                    "type": "string",
                    "description": "Empty string when unset.",
                    "example": "210000000"
                  },
                  "phone_country_code": {
                    "$ref": "#/components/schemas/V3DocumentPhoneCountryCode"
                  },
                  "mobile": {
                    "type": "string",
                    "description": "Empty string when unset.",
                    "example": "910000000"
                  },
                  "mobile_country_code": {
                    "$ref": "#/components/schemas/V3DocumentPhoneCountryCode"
                  },
                  "fiscal_id": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "255-character limit is the database column default, not an explicit validation.",
                    "example": "987654321"
                  },
                  "country": {
                    "type": "string",
                    "example": ""
                  },
                  "translated_country": {
                    "type": "string",
                    "description": "Client's fiscal country name in the request language.",
                    "example": "Portugal"
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "detail": {
                        "type": "string",
                        "description": "No enforced length limit; stored as a text column.",
                        "example": "456 Client Street"
                      },
                      "postal_code": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "255-character limit is the database column default, not an explicit validation.",
                        "example": "2000-002"
                      },
                      "city": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "255-character limit is the database column default, not an explicit validation.",
                        "example": "Porto"
                      },
                      "address_country": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "255-character limit is the database column default, not an explicit validation.",
                        "example": "PT"
                      }
                    }
                  }
                }
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "example": 484102115
                    },
                    "name": {
                      "type": "string",
                      "example": "Product Name",
                      "maxLength": 60,
                      "description": "Maximum 60 characters. Longer values are rejected with 422 (\"Code for the item is too long\")."
                    },
                    "description": {
                      "type": "string",
                      "example": "Product description",
                      "maxLength": 200,
                      "description": "Maximum 200 characters and at most 20 lines. Longer values are rejected with 422."
                    },
                    "unit_price": {
                      "type": "number",
                      "example": 100
                    },
                    "unit": {
                      "type": "string",
                      "description": "Must be one of a fixed set of supported unit values, not a length-limited free-text field.",
                      "example": "piece"
                    },
                    "quantity": {
                      "type": "number",
                      "example": 2
                    },
                    "tax": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "example": 1
                        },
                        "name": {
                          "type": "string",
                          "maxLength": 255,
                          "description": "255-character limit is the database column default; only presence and uniqueness are validated.",
                          "example": "IVA23"
                        },
                        "value": {
                          "type": "number",
                          "example": 23
                        }
                      }
                    },
                    "discount": {
                      "type": "number",
                      "example": 10
                    },
                    "subtotal": {
                      "type": "number",
                      "example": 180
                    },
                    "tax_amount": {
                      "type": "number",
                      "example": 41.4
                    },
                    "discount_amount": {
                      "type": "number",
                      "example": 20
                    },
                    "total": {
                      "type": "number",
                      "example": 221.4
                    },
                    "retention": {
                      "type": "number",
                      "example": 0
                    }
                  }
                }
              },
              "summary": {
                "type": "object",
                "properties": {
                  "sum": {
                    "type": "number",
                    "example": 200
                  },
                  "discount": {
                    "type": "number",
                    "example": 20
                  },
                  "before_taxes": {
                    "type": "number",
                    "example": 180
                  },
                  "taxes": {
                    "type": "number",
                    "example": 41.4
                  },
                  "total": {
                    "type": "number",
                    "example": 221.4
                  },
                  "currency": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "example": "Euro"
                      },
                      "code": {
                        "type": "string",
                        "example": "EUR"
                      },
                      "symbol": {
                        "type": "string",
                        "example": "€"
                      }
                    }
                  },
                  "retention": {
                    "type": "number",
                    "example": 0
                  },
                  "pay_progress": {
                    "type": "number",
                    "example": 0
                  },
                  "to_pay": {
                    "type": "number",
                    "example": 0
                  },
                  "total_paid": {
                    "type": "number",
                    "example": 0
                  },
                  "taxes_breakdown": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "category": {
                          "type": "string",
                          "example": "IVA23"
                        },
                        "items_value": {
                          "type": "number",
                          "example": 180
                        },
                        "tax_value": {
                          "type": "number",
                          "example": 41.4
                        }
                      }
                    }
                  },
                  "total_currency_rate": {
                    "type": "number",
                    "example": 0
                  },
                  "rate": {
                    "type": "number",
                    "example": 1
                  }
                }
              },
              "mb_reference": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "entity": {
                    "type": "string",
                    "example": "12345"
                  },
                  "value": {
                    "type": "number",
                    "example": 221.4
                  },
                  "reference": {
                    "type": "string",
                    "example": "123 456 789"
                  }
                }
              }
            }
          }
        }
      },
      "V3DocumentBatchesResponse": {
        "type": "object",
        "properties": {
          "document_batches": {
            "type": "array",
            "description": "List of document batches belonging to the authenticated account.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "name": {
                  "type": "string"
                },
                "count": {
                  "type": "integer"
                }
              }
            },
            "example": [
              {
                "id": 42,
                "name": "January 2024 import",
                "count": 15
              }
            ]
          }
        }
      },
      "V3CheckFinalizeResponse": {
        "type": "object",
        "properties": {
          "document_future_date": {
            "type": "boolean",
            "example": true
          },
          "has_earlier_draft": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "V3NewDocumentResponse": {
        "type": "object",
        "description": "Defaults and choice lists for building a new document of the requested type. Not wrapped in a root key. Entries marked `selected` are the defaults for the account (or for the client given in `client_id`).",
        "properties": {
          "due_date_choices": {
            "type": "array",
            "description": "Payment-term options in days. The client's (or account's) payment days are flagged `selected`; a value outside the fixed list replaces the `custom` entry.",
            "items": {
              "type": "object",
              "properties": {
                "value": {
                  "oneOf": [
                    {
                      "type": "integer"
                    },
                    {
                      "type": "string"
                    }
                  ],
                  "description": "Days, or `custom`."
                },
                "description": {
                  "type": "string"
                },
                "selected": {
                  "type": "boolean"
                }
              }
            },
            "example": [
              {
                "value": 0,
                "description": "Immediately"
              },
              {
                "value": 30,
                "description": "30 days",
                "selected": true
              },
              {
                "value": "custom",
                "description": "Other"
              }
            ]
          },
          "exemption_reasons": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "example": "M01"
                },
                "reason": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "selected": {
                  "type": "boolean"
                }
              }
            }
          },
          "sequences": {
            "type": "array",
            "description": "Series of this document type the account can issue in (Portuguese accounts only list series registered with the AT). When there is none, a single placeholder entry is returned with `id` null, `disabled` true and `serie` \"Choose a registered Sequence\" (or \"Choose a Sequence\" for foreign accounts).",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "example": 5259451
                },
                "serie": {
                  "type": "string",
                  "example": "2026"
                },
                "selected": {
                  "type": "boolean"
                },
                "disabled": {
                  "type": "boolean"
                }
              }
            }
          },
          "currencies": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 1
                },
                "name": {
                  "type": "string",
                  "example": "Euro"
                },
                "code": {
                  "type": "string",
                  "example": "EUR"
                },
                "symbol": {
                  "type": "string",
                  "example": "€"
                },
                "selected": {
                  "type": "boolean",
                  "description": "Set on the client's currency when `client_id` is given."
                }
              }
            }
          },
          "retention": {
            "type": "array",
            "description": "Withholding-tax options. The first entry (`id` and `value` null, \"Not applicable\") means no retention.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "value": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "description": {
                  "type": "string"
                }
              }
            }
          },
          "remarks": {
            "type": "string",
            "description": "Default observations — the client's (or account's) observations followed by the text of the default exemption reason.",
            "example": ""
          },
          "include_payment_reference": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "The account's \"add Multibanco reference by default\" preference. Null unless the plan includes MB, an MB provider is configured and the document type supports a payment reference.",
            "example": null
          },
          "has_configured_payment_service": {
            "type": "boolean",
            "example": false
          },
          "taxes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 756700
                },
                "name": {
                  "type": "string",
                  "example": "IVA23"
                },
                "region": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "PT"
                },
                "code": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "NOR"
                },
                "value": {
                  "type": "number",
                  "example": 23
                },
                "default_tax": {
                  "type": "integer",
                  "enum": [
                    0,
                    1
                  ],
                  "description": "1 for the account's default tax."
                }
              }
            }
          },
          "client": {
            "type": "object",
            "description": "Conditional — only present when `client_id` matches a client.",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "fiscal_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "address": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "postal_code": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      },
      "V3UpdateSummaryRequest": {
        "type": "object",
        "description": "The wrapper key matches the singular of the invoice type used in the path (invoice, invoice_receipt, simplified_invoice, credit_note, debit_note, or receipt) — shown here as \"invoice\". Using the wrong key returns a 422 (\"No invoice element provided\", with the expected key name).",
        "properties": {
          "invoice": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string",
                "format": "date",
                "example": "2026-04-16"
              },
              "due_date": {
                "type": "string",
                "format": "date",
                "example": "2026-05-16"
              },
              "retention": {
                "type": "number",
                "example": 100
              },
              "global_discount": {
                "type": "object",
                "properties": {
                  "value_type": {
                    "type": "string",
                    "example": "percentage"
                  },
                  "value": {
                    "type": "number",
                    "example": 50
                  }
                }
              },
              "items": {
                "type": "array",
                "description": "Invoice items.",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "maxLength": 60,
                      "description": "Maximum 60 characters. Longer values are rejected with 422 (\"Code for the item is too long\")."
                    },
                    "description": {
                      "type": "string",
                      "maxLength": 200,
                      "description": "Maximum 200 characters and at most 20 lines. Longer values are rejected with 422."
                    },
                    "unit_price": {
                      "type": "number"
                    },
                    "unit": {
                      "type": "string"
                    },
                    "quantity": {
                      "type": "number"
                    },
                    "discount": {
                      "type": "number"
                    },
                    "retention": {
                      "type": "number"
                    },
                    "tax": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "value": {
                          "type": "number"
                        }
                      }
                    }
                  }
                },
                "example": [
                  {
                    "name": "p2",
                    "description": "",
                    "unit_price": 10,
                    "unit": "",
                    "quantity": 1,
                    "tax": {
                      "name": "IVA23",
                      "value": 23
                    },
                    "discount": 0,
                    "retention": 0
                  },
                  {
                    "name": "p1",
                    "description": "Item description",
                    "unit_price": 10,
                    "quantity": 10,
                    "tax": {
                      "name": "IVA23",
                      "value": 23
                    },
                    "discount": 50
                  }
                ]
              }
            }
          }
        }
      },
      "V3UpdateSummaryResponse": {
        "type": "object",
        "properties": {
          "summary": {
            "type": "object",
            "properties": {
              "sum": {
                "type": "number",
                "example": 19.99
              },
              "discount": {
                "type": "number",
                "example": 0
              },
              "before_taxes": {
                "type": "number",
                "example": 19.99
              },
              "taxes": {
                "type": "number",
                "example": 4.6
              },
              "total": {
                "type": "number",
                "example": 24.59
              },
              "currency": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Euro"
                  },
                  "code": {
                    "type": "string",
                    "example": "EUR"
                  },
                  "symbol": {
                    "type": "string",
                    "example": "€"
                  }
                }
              },
              "retention": {
                "type": "number",
                "example": 0
              },
              "pay_progress": {
                "type": "number",
                "example": 0
              },
              "to_pay": {
                "type": "number",
                "example": 24.59
              },
              "total_paid": {
                "type": "number",
                "example": 0
              },
              "taxes_breakdown": {
                "type": "array",
                "description": "Breakdown of taxes applied.",
                "items": {
                  "type": "object",
                  "properties": {
                    "category": {
                      "type": "string"
                    },
                    "items_value": {
                      "type": "number"
                    },
                    "tax_value": {
                      "type": "number"
                    }
                  }
                },
                "example": [
                  {
                    "category": "IVA23",
                    "items_value": 10,
                    "tax_value": 2.3
                  },
                  {
                    "category": "IVA23",
                    "items_value": 9.99,
                    "tax_value": 2.3
                  }
                ]
              },
              "total_currency_rate": {
                "type": "number",
                "example": 0
              },
              "rate": {
                "type": "number",
                "example": 1
              }
            }
          }
        }
      },
      "V3InvoiceSummaryRequest": {
        "type": "object",
        "description": "Accepts every filter of `V3InvoicesQueryParams` (the invoice list filters) in the body; only the most common ones are listed here.",
        "properties": {
          "language": {
            "type": "string",
            "example": "Invoices"
          },
          "id": {
            "type": "array",
            "description": "List of document IDs to calculate the summary for.",
            "items": {
              "type": "string"
            },
            "example": [
              "541897"
            ]
          }
        }
      },
      "V3InvoiceSummaryResponse": {
        "type": "object",
        "properties": {
          "totals": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "example": 44
              },
              "pages": {
                "type": "integer",
                "example": 5
              },
              "statuses": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "canceled"
                ]
              },
              "total_corrections": {
                "type": "number",
                "example": 0
              },
              "total_corrections_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_drafts": {
                "type": "number",
                "example": 0
              },
              "total_drafts_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_canceled": {
                "type": "number",
                "example": 3516.96
              },
              "total_canceled_with_taxes": {
                "type": "number",
                "example": 4325.87
              },
              "total_due": {
                "type": "number",
                "example": 0
              },
              "total_due_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_overdue": {
                "type": "number",
                "example": 0
              },
              "total_overdue_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_paid_before_taxes": {
                "type": "number",
                "example": 0
              },
              "total_paid_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_before_taxes": {
                "type": "number",
                "example": 0
              },
              "total_taxes": {
                "type": "number",
                "example": 0
              },
              "total": {
                "type": "number",
                "example": 0
              }
            }
          }
        }
      },
      "V3CreateCommentRequest": {
        "type": "object",
        "required": [
          "comment"
        ],
        "description": "The `comment` wrapper is required; a request without it is not validated and fails with 500.",
        "properties": {
          "comment": {
            "type": "object",
            "required": [
              "message"
            ],
            "properties": {
              "message": {
                "type": "string",
                "minLength": 1,
                "maxLength": 255,
                "example": "This is a test comment"
              }
            }
          }
        }
      },
      "V3CommentResponse": {
        "type": "object",
        "properties": {
          "comment": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "example": 195860
              },
              "type": {
                "type": "string",
                "example": "Comment"
              },
              "event": {
                "type": "string",
                "example": "Comment",
                "description": "Human-readable, translated label of the event (e.g. `Created`, `Finalized`, `Comment`), not a stable key. Do not branch on it; use `type` instead."
              },
              "author": {
                "type": "string",
                "example": "user@invoicexpress.com"
              },
              "message": {
                "type": "string",
                "maxLength": 255,
                "example": "Test comment"
              },
              "date": {
                "type": "string",
                "format": "date-time",
                "example": "2026-05-12T15:50:30+01:00"
              },
              "can_change": {
                "type": "boolean",
                "example": true
              },
              "time_to_change": {
                "type": "integer",
                "example": 15
              }
            }
          }
        }
      },
      "V3MovementsResponse": {
        "type": "object",
        "properties": {
          "movements": {
            "type": "array",
            "description": "List of movements related to the document.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "type": {
                  "type": "string"
                },
                "total": {
                  "type": "number"
                },
                "root_path": {
                  "type": "string"
                },
                "date": {
                  "type": "string",
                  "format": "date"
                },
                "doc_id": {
                  "type": "integer"
                },
                "doc_root_path": {
                  "type": "string"
                },
                "pdf_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            },
            "example": [
              {
                "id": 12345,
                "type": "Payment",
                "total": 123.45,
                "root_path": "partial_payments",
                "date": "2025-01-31",
                "doc_id": 67890,
                "doc_root_path": "receipts",
                "pdf_url": "https://demo.app.invoicexpress.com/movements/12345.pdf"
              }
            ]
          }
        }
      },
      "V3PdfReadyResponse": {
        "type": "object",
        "properties": {
          "pdf": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "example": "https://s3.amazonaws.com/bucket/document.pdf"
              }
            }
          }
        }
      },
      "V3PdfProcessingResponse": {
        "type": "object",
        "properties": {
          "pdf": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "PDF file is being generated"
              }
            }
          }
        }
      },
      "V3QrCodeReadyResponse": {
        "type": "object",
        "properties": {
          "qr_code": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "example": "https://s3.amazonaws.com/bucket/qr_code"
              }
            }
          }
        }
      },
      "V3QrCodeProcessingResponse": {
        "type": "object",
        "properties": {
          "qr_code": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "example": "QR Code is being generated"
              }
            }
          }
        }
      },
      "V3SendDocumentRequest": {
        "type": "object",
        "description": "Every field is optional, including the `send` wrapper itself. Addresses are comma-separated lists; each one is validated and an invalid address fails the request with 422. Trial accounts can only send to the user's own email address.",
        "properties": {
          "send": {
            "type": "object",
            "properties": {
              "to": {
                "type": "string",
                "description": "Recipient(s). When blank, falls back to the document's client email, then to the account email (trial accounts always fall back to the user's own email).",
                "example": "client@example.com"
              },
              "email_cc": {
                "type": "string",
                "description": "Cc recipient(s).",
                "example": ""
              },
              "email_bcc": {
                "type": "string",
                "description": "Bcc recipient(s).",
                "example": ""
              },
              "subject": {
                "type": "string",
                "example": "Your document is ready"
              },
              "body": {
                "type": "string",
                "example": "Hello,\n\nPlease find your document attached.\n\nRegards,\ninvoicexpress\n"
              },
              "send_copy": {
                "type": "boolean",
                "description": "Also send a copy to the requesting user's email (added to `to`).",
                "example": false
              },
              "update_preferred_contact": {
                "type": "boolean",
                "description": "Save the `to` addresses as the client's preferred contact email.",
                "example": false
              },
              "document_url": {
                "type": "string",
                "description": "Link used for the \"view online\" button; defaults to the document permalink in the client's language.",
                "example": "https://web.invoicexpress.com/documents/541674bbfcdd182143fe2747524df08ab1367ef8255010?language=en"
              }
            }
          }
        }
      },
      "V3SendDocumentConfigResponse": {
        "type": "object",
        "properties": {
          "send": {
            "type": "object",
            "properties": {
              "to": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Null when the client has no email on file.",
                "example": "email@teste.com"
              },
              "email_cc": {
                "type": "string",
                "example": "cc1@example.com, cc2@example.com"
              },
              "email_bcc": {
                "type": "string",
                "example": "finance@example.com"
              },
              "subject": {
                "type": "string",
                "example": "Your invoice 2025/123 is ready"
              },
              "body": {
                "type": "string",
                "example": "Hello John,\nPlease find your invoice 2025/123 attached.\nRegards,\nCompany\n"
              },
              "send_copy": {
                "type": "boolean",
                "example": true
              }
            }
          }
        }
      },
      "V3SendDocumentActionResponse": {
        "type": "object",
        "description": "Flat object (no `send` wrapper) with the addresses the email was queued for. `email_cc` / `email_bcc` are only present when sent.",
        "properties": {
          "email_to": {
            "type": "string",
            "description": "Comma-separated recipients, including the user's own email when `send_copy` was true.",
            "example": "client@example.com"
          },
          "email_cc": {
            "type": "string",
            "example": "cc1@example.com,cc2@example.com"
          },
          "email_bcc": {
            "type": "string",
            "example": "finance@example.com"
          }
        }
      },
      "V3SendDocumentError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "client@example is an invalid email"
              }
            ]
          }
        }
      },
      "V3RelatedDocumentsResponse": {
        "type": "object",
        "properties": {
          "related_documents": {
            "type": "array",
            "description": "List of documents related to the specified document.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "type": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "sequence_number": {
                  "type": "string"
                },
                "total": {
                  "type": "number"
                },
                "root_path": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "id": 12345,
                "type": "Invoice",
                "status": "final",
                "sequence_number": "2025/000123",
                "total": 123.45,
                "root_path": "invoices"
              }
            ]
          }
        }
      },
      "V3TimelineResponse": {
        "type": "object",
        "properties": {
          "timeline": {
            "type": "array",
            "description": "List of timeline activities and events for the document.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "type": {
                  "type": "string"
                },
                "event": {
                  "type": "string",
                  "description": "Human-readable, translated label of the event (e.g. `Created`, `Finalized`, `Comment`), not a stable key. Do not branch on it; use `type` instead."
                },
                "author": {
                  "type": "string"
                },
                "message": {
                  "type": "object",
                  "description": "Event-specific payload — the keys vary by `event`, so treat this as a free-form object. `Created`/`Sent` entries carry `data.author`, `data.auth_user` and `notification_type`; state-change entries such as `Finalized` instead carry `[before, after]` pairs for fields like `status`, `sequence_number`, `document_number`, `document_serie`, `final_date`, `saft_hash`, `encrypted_doc`, `client_version` and `account_version`; `Paid` entries carry `total_paid` and `total_paid_before_taxes`.",
                  "additionalProperties": true,
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "author": {
                          "type": "string"
                        },
                        "auth_user": {
                          "type": "string"
                        }
                      }
                    },
                    "notification_type": {
                      "type": "string"
                    }
                  }
                },
                "to": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "date": {
                  "type": "string",
                  "format": "date-time"
                },
                "can_change": {
                  "type": "boolean"
                },
                "time_to_change": {
                  "type": "integer"
                }
              }
            },
            "example": [
              {
                "id": 2756411,
                "type": "Activity",
                "event": "Created",
                "author": "goncalo.correia@invoicexpress.com",
                "message": {
                  "data": {
                    "author": "goncalo.correia@invoicexpress.com",
                    "auth_user": "goncalo.correia@rupeal.com"
                  },
                  "notification_type": "invoice"
                },
                "to": "goncalopcorreia@hotmail.com",
                "date": "2026-07-27T16:00:44+01:00",
                "can_change": false,
                "time_to_change": 0
              },
              {
                "id": 2756412,
                "type": "Activity",
                "event": "Finalized",
                "author": "goncalo.correia@invoicexpress.com",
                "message": {
                  "status": [
                    "draft",
                    "sent"
                  ],
                  "sequence_number": [
                    "rascunho",
                    "110/INVOICEXPRESSDEMO"
                  ],
                  "document_number": [
                    null,
                    "110"
                  ],
                  "final_date": [
                    null,
                    "2026-07-27 17:23:50 +0100"
                  ]
                },
                "to": null,
                "date": "2026-07-27T17:23:50+01:00",
                "can_change": false,
                "time_to_change": 0
              }
            ]
          }
        }
      },
      "V3ChangeInvoiceStateRequest": {
        "type": "object",
        "description": "The wrapper key must match the singular of the invoice type used in the path (invoice, invoice_receipt, simplified_invoice, credit_note, debit_note, or receipt) — using the wrong key returns a 422 (\"Invalid root element, expected ...\"). Shown here as \"invoice\".",
        "required": [
          "invoice"
        ],
        "properties": {
          "invoice": {
            "type": "object",
            "required": [
              "state"
            ],
            "properties": {
              "state": {
                "type": "string",
                "description": "Target state event (e.g. finalized, deleted, canceled, settled, unsettled).",
                "example": "finalized"
              },
              "message": {
                "type": "string",
                "description": "Cancellation reason. Required when `state` is `canceled`; if it is missing or empty the API returns 422 with \"The cancellation reason is a required field\" (text in the account's language). Ignored for the other states. Returned as `cancel_reason` on the document.",
                "example": "Document issued by mistake"
              }
            }
          }
        }
      },
      "V3ChangeInvoiceStateResponse": {
        "type": "object",
        "properties": {
          "invoice": {
            "type": "object",
            "description": "Wrapper key matches the singular of the requested invoice type (invoice, invoice_receipt, simplified_invoice, credit_note, debit_note, or receipt).",
            "properties": {
              "id": {
                "type": "integer",
                "example": 257224047
              },
              "status": {
                "type": "string",
                "enum": [
                  "draft",
                  "final",
                  "settled",
                  "canceled",
                  "second_copy"
                ],
                "description": "A finalized document is returned as `final` (the list endpoint returns the same document as `sent`).",
                "example": "canceled"
              },
              "archived": {
                "type": "boolean",
                "example": false
              },
              "cancel_reason": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "No enforced length limit; stored as a text column (maps to cancel_message).",
                "example": "Test cancellation"
              },
              "type": {
                "type": "string",
                "example": "Invoice"
              },
              "sequence_number": {
                "type": "string",
                "example": "23/INVOICEXPRESSDEMO"
              },
              "inverted_sequence_number": {
                "type": "string",
                "example": "INVOICEXPRESSDEMO/23"
              },
              "sequence_id": {
                "type": "integer",
                "example": 5259451
              },
              "date": {
                "type": "string",
                "description": "dd/mm/yyyy",
                "example": "13/05/2026"
              },
              "due_date": {
                "type": "string",
                "description": "dd/mm/yyyy",
                "example": "13/06/2026"
              },
              "reference": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 255,
                "example": null
              },
              "observations": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "No enforced length limit; stored as a text column.",
                "example": null
              },
              "retention": {
                "type": [
                  "number",
                  "null"
                ],
                "example": null
              },
              "permalink": {
                "type": "string",
                "example": "https://web.invoicexpress.com/documents/abc123"
              },
              "saft_hash": {
                "type": "string",
                "example": "Xbsc",
                "description": "No enforced character limit (text column)."
              },
              "sum": {
                "type": "number",
                "example": 100
              },
              "discount": {
                "type": "number",
                "example": 0
              },
              "before_taxes": {
                "type": "number",
                "example": 100
              },
              "taxes": {
                "type": "number",
                "example": 23
              },
              "total": {
                "type": "number",
                "example": 123
              },
              "currency": {
                "type": "string",
                "example": "Euro"
              },
              "client": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer",
                    "example": 194666511
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 100,
                    "example": "Test Client"
                  }
                }
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "example": "Test Item",
                      "maxLength": 60,
                      "description": "Maximum 60 characters. Longer values are rejected with 422 (\"Code for the item is too long\")."
                    },
                    "description": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "example": null,
                      "maxLength": 200,
                      "description": "Maximum 200 characters and at most 20 lines. Longer values are rejected with 422."
                    },
                    "unit_price": {
                      "type": "string",
                      "example": "100.0"
                    },
                    "unit": {
                      "type": "string",
                      "description": "Must be one of a fixed set of supported unit values, not a length-limited free-text field.",
                      "example": "service"
                    },
                    "quantity": {
                      "type": "string",
                      "example": "1.0"
                    },
                    "tax": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "example": 756700
                        },
                        "name": {
                          "type": "string",
                          "maxLength": 255,
                          "description": "255-character limit is the database column default; only presence and uniqueness are validated.",
                          "example": "IVA23"
                        },
                        "value": {
                          "type": "number",
                          "example": 23
                        }
                      }
                    },
                    "discount": {
                      "type": "number",
                      "example": 0
                    },
                    "subtotal": {
                      "type": "number",
                      "example": 100
                    },
                    "tax_amount": {
                      "type": "number",
                      "example": 23
                    },
                    "discount_amount": {
                      "type": "number",
                      "example": 0
                    },
                    "total": {
                      "type": "number",
                      "example": 123
                    }
                  }
                }
              },
              "atcud": {
                "type": "string",
                "example": "N/D"
              }
            }
          }
        }
      },
      "V3PartialPaymentRequest": {
        "type": "object",
        "required": [
          "partial_payment"
        ],
        "properties": {
          "partial_payment": {
            "type": "object",
            "required": [
              "amount"
            ],
            "properties": {
              "amount": {
                "type": "number",
                "example": 150.5
              },
              "payment_date": {
                "type": "string",
                "description": "dd/mm/yyyy",
                "example": "15/01/2024"
              },
              "payment_mechanism": {
                "type": "string",
                "maxLength": 255,
                "description": "Payment mechanism code (e.g. TB, MB, CC). 255-character limit is the database column default.",
                "example": "TB"
              },
              "note": {
                "type": "string",
                "description": "Stored in full on the receipt (`observations`, a text column). The copy on the treasury movement is truncated to 255 characters. If a value still reaches a 255-character column, the API answers 422 `The note is too long (maximum 255 characters). Please shorten it and try again.`",
                "example": "Payment for invoice 123456"
              }
            }
          }
        }
      },
      "V3PartialPaymentCreatedResponse": {
        "type": "object",
        "required": [
          "receipt"
        ],
        "description": "JSON response including the generated receipt for the partial payment.",
        "properties": {
          "receipt": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "example": 256124749
              },
              "status": {
                "type": "string",
                "example": "final"
              },
              "archived": {
                "type": "boolean",
                "example": false
              },
              "type": {
                "type": "string",
                "example": "Receipt"
              },
              "sequence_number": {
                "type": "string",
                "example": "14/INVOICEXPRESSDEMO"
              },
              "inverted_sequence_number": {
                "type": "string",
                "example": "INVOICEXPRESSDEMO/14"
              },
              "sequence_id": {
                "type": "integer",
                "example": 5259454
              },
              "date": {
                "type": "string",
                "description": "dd/mm/yyyy",
                "example": "30/04/2026"
              },
              "due_date": {
                "type": "string",
                "description": "dd/mm/yyyy",
                "example": "30/04/2026"
              },
              "reference": {
                "type": "string",
                "maxLength": 255,
                "example": ""
              },
              "observations": {
                "type": "string",
                "description": "No enforced length limit; stored as a text column.",
                "example": "Payment for invoice 123456"
              },
              "retention": {
                "type": [
                  "number",
                  "null"
                ],
                "example": null
              },
              "permalink": {
                "type": "string",
                "format": "uri",
                "example": "https://web.invoicexpress.com/documents/256124749625970261deda875ee3e3138ffed1a5437d8dc8b"
              },
              "saft_hash": {
                "type": "string",
                "example": "jd5I",
                "description": "No enforced character limit (text column)."
              },
              "sum": {
                "type": "number",
                "example": 100
              },
              "discount": {
                "type": "number",
                "example": 0
              },
              "before_taxes": {
                "type": "number",
                "example": 100
              },
              "taxes": {
                "type": "number",
                "example": 23
              },
              "total": {
                "type": "number",
                "example": 123
              },
              "currency": {
                "type": "string",
                "example": "Euro"
              },
              "client": {
                "type": "object",
                "description": "The receipt's client. `id` and `name` are always present; every other field is omitted when blank on the client.",
                "required": [
                  "id",
                  "name"
                ],
                "properties": {
                  "id": {
                    "type": "integer",
                    "example": 192905674
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 100,
                    "example": "teste"
                  },
                  "email": {
                    "type": "string",
                    "example": "client@example.com"
                  },
                  "address": {
                    "type": "string"
                  },
                  "postal_code": {
                    "type": "string"
                  },
                  "country": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "Address country. 255-character limit is the database column default, not an explicit validation.",
                    "example": "Portugal"
                  },
                  "code": {
                    "type": "string"
                  },
                  "city": {
                    "type": "string"
                  },
                  "fiscal_id": {
                    "type": "string"
                  },
                  "website": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "fax": {
                    "type": "string"
                  },
                  "observations": {
                    "type": "string"
                  }
                }
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object"
                },
                "example": []
              },
              "atcud": {
                "type": "string",
                "example": "N/D"
              }
            }
          }
        },
        "example": {
          "receipt": {
            "id": 256124749,
            "status": "final",
            "archived": false,
            "type": "Receipt",
            "sequence_number": "14/INVOICEXPRESSDEMO",
            "inverted_sequence_number": "INVOICEXPRESSDEMO/14",
            "sequence_id": 5259454,
            "date": "30/04/2026",
            "due_date": "30/04/2026",
            "reference": "",
            "observations": "Payment for invoice 123456",
            "retention": null,
            "permalink": "https://web.invoicexpress.com/documents/256124749625970261deda875ee3e3138ffed1a5437d8dc8b",
            "saft_hash": "jd5I",
            "sum": 100,
            "discount": 0,
            "before_taxes": 100,
            "taxes": 23,
            "total": 123,
            "currency": "Euro",
            "client": {
              "id": 192905674,
              "name": "teste",
              "email": "client@example.com",
              "country": "Portugal"
            },
            "items": [],
            "atcud": "N/D"
          }
        }
      },
      "V3PartialPayment404Error": {
        "type": "array",
        "description": "Array of [field, message] tuples — the same shape as the 422 response, not the usual errors-array-of-objects shape.",
        "items": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "minItems": 2,
          "maxItems": 2
        },
        "example": [
          [
            "base",
            "document not found"
          ]
        ]
      },
      "V3PartialPaymentValidationError": {
        "type": "array",
        "description": "Array of [field, message] tuples — not the usual errors-array-of-objects shape.",
        "items": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "minItems": 2,
          "maxItems": 2
        },
        "example": [
          [
            "document",
            "Invalid state for partial document [draft]"
          ],
          [
            "base",
            "Partial payment is invalid."
          ]
        ]
      },
      "V3ChangeDocumentStateError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "The cancellation reason is a required field"
              }
            ]
          }
        }
      },
      "V3UnauthorizedError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "Authentication Error"
              }
            ]
          }
        }
      },
      "V3NotFoundError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "Resource not found"
              }
            ]
          }
        }
      },
      "V3ServerError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "An unexpected error occurred"
              }
            ]
          }
        }
      },
      "V3TransformDocumentError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "description": "Lista de erros retornada quando a transformação falha.",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "Unable to transform the specified document"
              }
            ]
          }
        }
      },
      "V3CreateCommentError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "description": "Validation errors for the comment: `Message can't be blank` or `Message is too long (maximum is 255 characters)`.",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "Message can't be blank"
              }
            ]
          }
        }
      },
      "V3DeleteCommentError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "description": "Lista de erros retornada quando um comentário não pode ser apagado.",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "Comment cannot be deleted"
              }
            ]
          }
        }
      },
      "V3SendError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "Email service is disabled for your account. To activate it, please contact us at support@invoicexpress.com."
              }
            ]
          }
        }
      },
      "V3QrCodeDraftError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "QR code is not available for draft documents."
              }
            ]
          }
        }
      },
      "V3ArchiveDraftError": {
        "type": "object",
        "description": "Returned when archiving/unarchiving a draft document, or when the update fails model validation (one entry per message).",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "Can't archive draft document"
              }
            ]
          }
        }
      },
      "V3SequenceNameError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "param is missing or the value is empty or invalid: name"
              }
            ]
          }
        }
      },
      "V3PdfGenerationError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "description": "Lista de erros retornada quando a geração do PDF falha.",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "There was an error generating PDF file"
              }
            ]
          }
        }
      },
      "V3SendConfigError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "description": "Lista de erros retornada quando falha a obtenção da configuração de envio.",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "There was an error retrieving send document configuration"
              }
            ]
          }
        }
      },
      "V3UpdateInvoiceSummaryError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "description": "Lista de erros de validação devolvida ao tentar atualizar a fatura com dados em falta ou inválidos.",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "Date can't be blank"
              },
              {
                "error": "Due date can't be blank"
              }
            ]
          }
        }
      },
      "V3GuideListResponse": {
        "type": "object",
        "properties": {
          "guides": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 541674
                },
                "sequence_number": {
                  "type": "string",
                  "example": "serie_name/4"
                },
                "sequence": {
                  "type": "string",
                  "example": "serie_name"
                },
                "type": {
                  "type": "string",
                  "example": "Transport"
                },
                "license_plate": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "AB-CD-12",
                  "maxLength": 255,
                  "description": "Always present; `null` when not set. 255-character DB default; not explicitly validated."
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "draft",
                    "sent",
                    "canceled",
                    "second_copy"
                  ],
                  "description": "Raw stored status. A finalized guide is `sent` here, while show and change-state return it as `final`.",
                  "example": "canceled"
                },
                "archived": {
                  "type": "boolean",
                  "example": false
                },
                "client_name": {
                  "type": "string",
                  "example": "John Doe"
                },
                "reference": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "maxLength": 255,
                  "example": "PO-1234",
                  "description": "The document's free-text reference, the same value the `reference` filter searches. `null` when the document has none."
                },
                "date": {
                  "type": "string",
                  "example": "2023-01-03 00:00:00 +0000"
                },
                "loaded_at": {
                  "type": "string",
                  "example": "2023-01-03 12:00:00 +0000"
                },
                "total": {
                  "type": "number",
                  "example": 6.15
                },
                "total_before_taxes": {
                  "type": "number",
                  "example": 5
                },
                "token": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Public document token; `null` when the guide has none.",
                  "example": "541674bbfcdd182143fe2747524df08ab1367ef8255010"
                }
              }
            }
          },
          "totals": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "example": 44
              },
              "pages": {
                "type": "integer",
                "description": "`count / per_page` rounded to the nearest integer, not rounded up — it can be one less than the real number of pages (e.g. 44 guides at 10 per page gives 4, although page 5 exists). Use `count` to decide whether more pages exist.",
                "example": 4
              },
              "statuses": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Distinct statuses of the guides on the current page only — not of the whole filtered result set.",
                "example": [
                  "canceled"
                ]
              }
            }
          }
        }
      },
      "V3GuidesQueryParams": {
        "type": "object",
        "description": "Optional filters and pagination for listing guides (sent as query string parameters).",
        "properties": {
          "language": {
            "type": "string",
            "description": "Language of the response",
            "example": "pt"
          },
          "items_per_page": {
            "type": "integer",
            "description": "Number of items per page",
            "example": 10
          },
          "page": {
            "type": "integer",
            "description": "Page number",
            "example": 1
          },
          "id": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Filter by one or more document ids",
            "example": [
              "541897"
            ]
          },
          "except_id": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Exclude these document ids",
            "example": [
              "541897"
            ]
          },
          "sort": {
            "type": "string",
            "description": "Field to sort by",
            "example": "document_type"
          },
          "sort_order": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "description": "Order of sorting (asc/desc)",
            "example": "desc"
          },
          "text": {
            "type": "string",
            "description": "Text to search for",
            "example": "asdasdwqe"
          },
          "non_archived": {
            "type": "boolean",
            "description": "Filter for non-archived items",
            "example": true
          },
          "archived": {
            "type": "boolean",
            "description": "Filter for archived items",
            "example": false
          },
          "reference": {
            "type": "string",
            "description": "Reference identifier",
            "example": "123asd"
          },
          "show_iva": {
            "type": "boolean",
            "description": "Show IVA",
            "example": true
          },
          "type": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Document type filter",
            "example": [
              "invoice"
            ]
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Status filter",
            "example": [
              "draft"
            ]
          },
          "client_id": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Client id filter",
            "example": [
              "541897"
            ]
          },
          "plugin": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Plugin filter",
            "example": [
              "541897123-asdasdasd-zxcas123"
            ]
          },
          "serie_name": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Serie name filter",
            "example": [
              "SerieA"
            ]
          },
          "date[from]": {
            "type": "string",
            "format": "date",
            "description": "Document date range start",
            "example": "2026-04-27"
          },
          "date[to]": {
            "type": "string",
            "format": "date",
            "description": "Document date range end",
            "example": "2026-04-27"
          },
          "loaded_at[from]": {
            "type": "string",
            "format": "date",
            "description": "Loaded-at range start",
            "example": "2026-04-27"
          },
          "loaded_at[to]": {
            "type": "string",
            "format": "date",
            "description": "Loaded-at range end",
            "example": "2026-04-27"
          },
          "total_before_taxes[from]": {
            "type": "number",
            "description": "Total before taxes range start"
          },
          "total_before_taxes[to]": {
            "type": "number",
            "description": "Total before taxes range end"
          },
          "total_with_taxes[from]": {
            "type": "number",
            "description": "Total with taxes range start"
          },
          "total_with_taxes[to]": {
            "type": "number",
            "description": "Total with taxes range end"
          }
        }
      },
      "V3CreateGuideRequest": {
        "type": "object",
        "description": "The wrapper key must match the singular of the guide type used in the path (shipping, transport, or devolution) — shown here as \"transport\". Keys not listed here are dropped by the server's parameter allowlist. The same body is used to update a draft guide; on update the item list replaces the existing items.",
        "required": [
          "transport"
        ],
        "properties": {
          "proprietary_uid": {
            "type": "string",
            "description": "Your own idempotency identifier for the document (create only). Accepted here at the top level or inside the wrapper; a repeated value returns the guide already created with it instead of creating a new one.",
            "example": "order-10045"
          },
          "transport": {
            "type": "object",
            "required": [
              "loaded_at",
              "items"
            ],
            "properties": {
              "date": {
                "type": "string",
                "format": "date",
                "example": "2026-07-13"
              },
              "due_date": {
                "type": "string",
                "format": "date",
                "example": "2026-07-13"
              },
              "loaded_at": {
                "type": "string",
                "description": "Load date and time. Required, and must not be in the past; otherwise the API returns 422 `Load date must be on or after <current date and time>`.",
                "example": "2026-07-13 13:07:00"
              },
              "license_plate": {
                "type": "string",
                "maxLength": 255,
                "example": "00-AA-00"
              },
              "load_site": {
                "type": "string",
                "description": "Loading place (foreign accounts).",
                "example": "Warehouse A"
              },
              "delivery_site": {
                "type": "string",
                "description": "Delivery place (foreign accounts).",
                "example": "Client store"
              },
              "address_from": {
                "$ref": "#/components/schemas/V3GuideAddress"
              },
              "address_to": {
                "$ref": "#/components/schemas/V3GuideAddress"
              },
              "reference": {
                "type": "string",
                "maxLength": 255,
                "example": "PO-1234"
              },
              "observations": {
                "type": "string",
                "description": "No enforced length limit; stored as a text column.",
                "example": "Fragile goods"
              },
              "sequence_id": {
                "type": "integer",
                "description": "Id of the sequence (series) to issue the guide in. The account's default sequence is used when omitted.",
                "example": 5259467
              },
              "manual_sequence_number": {
                "type": "string",
                "maxLength": 255,
                "example": "001"
              },
              "tax_exemption": {
                "type": "string",
                "description": "AT tax exemption code (e.g. `M01`).",
                "example": "M01"
              },
              "retention": {
                "type": "number",
                "description": "Withholding tax rate (percentage). Only applied when it matches an active retention base.",
                "example": 0
              },
              "global_discount": {
                "type": [
                  "object",
                  "null"
                ],
                "description": "Document-level discount. Send `null` to remove an existing discount.",
                "properties": {
                  "value_type": {
                    "type": "string",
                    "enum": [
                      "percentage",
                      "absolute"
                    ],
                    "example": "percentage"
                  },
                  "value": {
                    "type": "number",
                    "example": 10
                  }
                }
              },
              "currency_code": {
                "type": "string",
                "description": "Only applied when the account's plan includes multi-currency.",
                "example": "EUR"
              },
              "rate": {
                "type": "number",
                "example": 1
              },
              "client_id": {
                "type": "integer",
                "description": "Id of an existing client. Alternative to `client.id`.",
                "example": 456
              },
              "client": {
                "type": "object",
                "description": "Resolved by `id` first, then by `name` / `code`; a client that does not exist is created.",
                "properties": {
                  "id": {
                    "type": "integer",
                    "example": 456
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 100,
                    "example": "John Doe"
                  },
                  "code": {
                    "type": "string",
                    "example": "C001"
                  },
                  "email": {
                    "type": "string",
                    "example": "john@example.com"
                  },
                  "fiscal_id": {
                    "type": "string",
                    "example": "987654321"
                  },
                  "address": {
                    "type": "string",
                    "example": "456 Client Street"
                  },
                  "postal_code": {
                    "type": "string",
                    "example": "2000-002"
                  },
                  "city": {
                    "type": "string",
                    "example": "Porto"
                  },
                  "country": {
                    "type": "string",
                    "example": "Portugal"
                  }
                }
              },
              "items": {
                "type": "array",
                "minItems": 1,
                "description": "At least one item is required.",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "maxLength": 60,
                      "example": "Product Name"
                    },
                    "description": {
                      "type": "string",
                      "maxLength": 200,
                      "example": "Product description"
                    },
                    "unit_price": {
                      "type": "number",
                      "example": 100
                    },
                    "unit": {
                      "type": "string",
                      "example": "unit"
                    },
                    "quantity": {
                      "type": "number",
                      "example": 2
                    },
                    "discount": {
                      "type": "number",
                      "example": 0
                    },
                    "tax": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "example": 1
                        },
                        "name": {
                          "type": "string",
                          "example": "IVA23"
                        },
                        "value": {
                          "type": "number",
                          "example": 23
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "V3GuideWriteError": {
        "type": "object",
        "description": "Validation failure when creating or updating a guide. Each entry carries one message.",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "No transport element provided"
              },
              {
                "error": "No items element provided"
              },
              {
                "error": "No address_from element provided"
              }
            ]
          }
        }
      },
      "V3NewGuideResponse": {
        "type": "object",
        "description": "Form defaults and choices for creating a new guide. Nothing is created. Labels follow the `language` query parameter, then the account's language.",
        "properties": {
          "due_date_choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "value": {
                  "type": [
                    "integer",
                    "string"
                  ],
                  "example": 30
                },
                "description": {
                  "type": "string",
                  "example": "30 days"
                },
                "selected": {
                  "type": "boolean",
                  "description": "Only on the choice matching the client's (or account's) payment days."
                }
              }
            }
          },
          "exemption_reasons": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "example": "M01"
                },
                "reason": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "selected": {
                  "type": "boolean"
                }
              }
            }
          },
          "sequences": {
            "type": "array",
            "description": "Sequences of this guide type (registered ones only for Portuguese accounts). When there is none, a single placeholder entry with `id` null and `disabled` true is returned.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "example": 5259467
                },
                "serie": {
                  "type": "string",
                  "example": "2026"
                },
                "selected": {
                  "type": "boolean"
                },
                "disabled": {
                  "type": "boolean"
                }
              }
            }
          },
          "currencies": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 1
                },
                "name": {
                  "type": "string",
                  "example": "Euro"
                },
                "code": {
                  "type": "string",
                  "example": "EUR"
                },
                "symbol": {
                  "type": "string",
                  "example": "€"
                },
                "selected": {
                  "type": "boolean"
                }
              }
            }
          },
          "retention": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "value": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "description": {
                  "type": "string",
                  "example": "Not applicable"
                }
              }
            }
          },
          "remarks": {
            "type": "string",
            "description": "Default observations plus the exemption reason text.",
            "example": ""
          },
          "include_payment_reference": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "has_configured_payment_service": {
            "type": "boolean",
            "example": false
          },
          "taxes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 756700
                },
                "name": {
                  "type": "string",
                  "example": "IVA23"
                },
                "region": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "PT"
                },
                "code": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "NOR"
                },
                "value": {
                  "type": "number",
                  "example": 23
                },
                "default_tax": {
                  "type": "integer",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 1
                }
              }
            }
          },
          "countries": {
            "type": "array",
            "description": "Country choices for `address_from` / `address_to`. Send `name` back, not `translated_name`.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 1
                },
                "name": {
                  "type": "string",
                  "example": "Portugal"
                },
                "translated_name": {
                  "type": "string",
                  "example": "Portugal"
                }
              }
            }
          },
          "client": {
            "type": "object",
            "description": "Only present when `client_id` is sent.",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "fiscal_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "address": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "postal_code": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      },
      "V3GuideSummaryRequest": {
        "type": "object",
        "properties": {
          "id": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "541897"
            ]
          }
        }
      },
      "V3UpdateSummaryGuideRequest": {
        "type": "object",
        "description": "The wrapper key matches the singular of the guide type used in the path (transport, shipping, or devolution) — shown here as \"transport\".",
        "properties": {
          "transport": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string",
                "format": "date",
                "example": "2026-04-16"
              },
              "due_date": {
                "type": "string",
                "format": "date",
                "example": "2026-05-16"
              },
              "retention": {
                "type": "number",
                "example": 100
              },
              "global_discount": {
                "type": "object",
                "properties": {
                  "value_type": {
                    "type": "string",
                    "example": "percentage"
                  },
                  "value": {
                    "type": "number",
                    "example": 50
                  }
                }
              },
              "items": {
                "type": "array",
                "description": "Invoice items.",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "maxLength": 60,
                      "description": "Maximum 60 characters. Longer values are rejected with 422 (\"Code for the item is too long\")."
                    },
                    "description": {
                      "type": "string",
                      "maxLength": 200,
                      "description": "Maximum 200 characters and at most 20 lines. Longer values are rejected with 422."
                    },
                    "unit_price": {
                      "type": "number"
                    },
                    "unit": {
                      "type": "string",
                      "description": "Must be one of a fixed set of supported unit values, not a free-length string."
                    },
                    "quantity": {
                      "type": "number"
                    },
                    "discount": {
                      "type": "number"
                    },
                    "retention": {
                      "type": "number"
                    },
                    "tax": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "value": {
                          "type": "number"
                        }
                      }
                    }
                  }
                },
                "example": [
                  {
                    "name": "p2",
                    "description": "",
                    "unit_price": 10,
                    "unit": "",
                    "quantity": 1,
                    "tax": {
                      "name": "IVA23",
                      "value": 23
                    },
                    "discount": 0,
                    "retention": 0
                  },
                  {
                    "name": "p1",
                    "description": "Item description",
                    "unit_price": 10,
                    "quantity": 10,
                    "tax": {
                      "name": "IVA23",
                      "value": 23
                    },
                    "discount": 50
                  }
                ]
              }
            }
          }
        }
      },
      "V3GuideSummaryResponse": {
        "type": "object",
        "properties": {
          "totals": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "example": 44
              },
              "pages": {
                "type": "integer",
                "example": 5
              },
              "statuses": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "canceled"
                ]
              }
            }
          }
        }
      },
      "V3GuideDocumentResponse": {
        "type": "object",
        "properties": {
          "transport": {
            "type": "object",
            "description": "Wrapper key matches the singular of the requested guide type (transport, shipping, or devolution).",
            "properties": {
              "id": {
                "type": "integer",
                "example": 263315060
              },
              "status": {
                "type": "string",
                "example": "draft"
              },
              "archived": {
                "type": "boolean",
                "example": false
              },
              "type": {
                "type": "string",
                "example": "Transport"
              },
              "sequence_number": {
                "type": "string",
                "example": "draft"
              },
              "inverted_sequence_number": {
                "type": "string",
                "example": "draft"
              },
              "sequence_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": 5259467
              },
              "atcud": {
                "type": "string",
                "example": "N/A"
              },
              "saft_hash": {
                "type": "string",
                "description": "Only present once the guide has been finalized — absent while it is still a draft.",
                "example": "vaDf"
              },
              "tax_exemption": {
                "type": "string",
                "example": "M01",
                "maxLength": 255,
                "description": "255-character database column default (column `tax_exemption_code`); effectively an enum of AT exemption codes."
              },
              "date": {
                "type": "string",
                "format": "date",
                "example": "2026-07-13"
              },
              "due_date": {
                "type": "string",
                "format": "date",
                "example": "2026-07-13"
              },
              "reference": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "maxLength": 255
              },
              "observations": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "description": "No enforced length limit (text column)."
              },
              "token": {
                "type": "string",
                "example": "263315060c9d7840b5909668386f4a9c93d4b3c4b98ab064e"
              },
              "permalink": {
                "type": "string",
                "example": "https://web.invoicexpress.com/documents/263315060c9d7840b5909668386f4a9c93d4b3c4b98ab064e?language=pt"
              },
              "retention": {
                "type": "number",
                "example": 0
              },
              "global_discount": {
                "$ref": "#/components/schemas/V3DocumentGlobalDiscount"
              },
              "loaded_at": {
                "type": "string",
                "example": "2026-07-13 13:07:00"
              },
              "license_plate": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "maxLength": 255,
                "description": "255-character DB default; not explicitly validated."
              },
              "at_doc_code_id": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "maxLength": 255,
                "readOnly": true,
                "description": "Read-only — written by the AT gateway when the guide is registered, never accepted from callers. 255-character DB default."
              },
              "address_from": {
                "type": "object",
                "description": "Returned for Portuguese accounts. Accounts that are not Portuguese get `load_site` and `delivery_site` instead of `address_from` and `address_to`.",
                "properties": {
                  "detail": {
                    "type": "string",
                    "example": "123 Loading Street",
                    "maxLength": 255,
                    "description": "255-character DB default on the Address model (a string column). The API re-inserts line breaks roughly every 35 characters before storing, so a value close to 255 can overflow the column — stay well under the limit."
                  },
                  "postal_code": {
                    "type": "string",
                    "example": "1000-001",
                    "maxLength": 255,
                    "description": "255-character DB default."
                  },
                  "city": {
                    "type": "string",
                    "example": "Lisbon",
                    "maxLength": 255,
                    "description": "255-character DB default."
                  },
                  "country": {
                    "type": "string",
                    "example": "Portugal",
                    "maxLength": 255,
                    "description": "Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal. 255-character DB default."
                  }
                }
              },
              "address_to": {
                "type": "object",
                "properties": {
                  "detail": {
                    "type": "string",
                    "example": "456 Delivery Street",
                    "maxLength": 255,
                    "description": "255-character DB default on the Address model (a string column). The API re-inserts line breaks roughly every 35 characters before storing, so a value close to 255 can overflow the column — stay well under the limit."
                  },
                  "postal_code": {
                    "type": "string",
                    "example": "2000-002",
                    "maxLength": 255,
                    "description": "255-character DB default."
                  },
                  "city": {
                    "type": "string",
                    "example": "Porto",
                    "maxLength": 255,
                    "description": "255-character DB default."
                  },
                  "country": {
                    "type": "string",
                    "example": "Portugal",
                    "maxLength": 255,
                    "description": "Not stored on the address itself — resolved through a tax-location name lookup, falling back to Portugal. 255-character DB default."
                  }
                }
              },
              "load_site": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "123 Loading Street, Lisbon",
                "description": "Free-text load site. Returned instead of `address_from` for accounts that are not Portuguese (simple address model). No enforced length limit (text column)."
              },
              "delivery_site": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "456 Delivery Street, Porto",
                "description": "Free-text delivery site. Returned instead of `address_to` for accounts that are not Portuguese (simple address model). No enforced length limit (text column)."
              },
              "owner_invoice_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": null
              },
              "raw_owner_invoice": {
                "$ref": "#/components/schemas/V3DocumentRawOwnerInvoice"
              },
              "currency": {
                "$ref": "#/components/schemas/V3DocumentCurrency"
              },
              "auto_add_related_document": {
                "type": "boolean",
                "example": false
              },
              "qr_code": {
                "$ref": "#/components/schemas/V3DocumentQrCodeField"
              },
              "digital_signed": {
                "$ref": "#/components/schemas/V3DocumentDigitalSignedField"
              },
              "include_payment_reference": {
                "$ref": "#/components/schemas/V3DocumentIncludePaymentReferenceField"
              },
              "account": {
                "type": "object",
                "properties": {
                  "organization_name": {
                    "type": "string",
                    "example": "invoicexpress"
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "detail": {
                        "type": "string",
                        "example": "Avenida Duque D'Avila, Saldanha"
                      },
                      "postal_code": {
                        "type": "string",
                        "example": "1500-555"
                      },
                      "city": {
                        "type": "string",
                        "example": "Lisbon"
                      },
                      "country": {
                        "type": "string",
                        "example": "Portugal"
                      },
                      "translated_country": {
                        "type": "string",
                        "description": "Country name in the request language.",
                        "example": "Portugal"
                      }
                    }
                  },
                  "email": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "info@mycompany.com"
                  },
                  "phone": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": null
                  },
                  "phone_country_code": {
                    "$ref": "#/components/schemas/V3DocumentPhoneCountryCode"
                  },
                  "phone_indicative_printed": {
                    "$ref": "#/components/schemas/V3DocumentPhoneIndicativePrinted"
                  },
                  "website": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": null
                  },
                  "footer": {
                    "$ref": "#/components/schemas/V3DocumentAccountFooter"
                  },
                  "fiscal_id": {
                    "type": "string",
                    "example": "999999990"
                  },
                  "logo": {
                    "type": "string",
                    "example": ""
                  },
                  "bank_data": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "example": "IBAN"
                        },
                        "value": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "example": null
                        }
                      }
                    }
                  }
                }
              },
              "client": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer",
                    "example": 89895780
                  },
                  "name": {
                    "type": "string",
                    "example": "John Doe",
                    "maxLength": 100
                  },
                  "email": {
                    "type": "string",
                    "example": "john@example.com",
                    "maxLength": 254
                  },
                  "phone": {
                    "type": "string",
                    "description": "Empty string when unset.",
                    "example": "210000000"
                  },
                  "phone_country_code": {
                    "$ref": "#/components/schemas/V3DocumentPhoneCountryCode"
                  },
                  "mobile": {
                    "type": "string",
                    "description": "Empty string when unset.",
                    "example": "910000000"
                  },
                  "mobile_country_code": {
                    "$ref": "#/components/schemas/V3DocumentPhoneCountryCode"
                  },
                  "fiscal_id": {
                    "type": "string",
                    "example": "987654321",
                    "maxLength": 255,
                    "description": "255-character DB default; not explicitly validated."
                  },
                  "country": {
                    "type": "string",
                    "example": "Portugal"
                  },
                  "translated_country": {
                    "type": "string",
                    "description": "Client's fiscal country name in the request language.",
                    "example": "Portugal"
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "detail": {
                        "type": "string",
                        "example": "456 Client Street",
                        "description": "No enforced length limit (text column)."
                      },
                      "postal_code": {
                        "type": "string",
                        "example": "2000-002",
                        "maxLength": 255,
                        "description": "255-character DB default."
                      },
                      "city": {
                        "type": "string",
                        "example": "Porto",
                        "maxLength": 255,
                        "description": "255-character DB default."
                      },
                      "address_country": {
                        "type": "string",
                        "example": "PT",
                        "maxLength": 255,
                        "description": "255-character DB default."
                      }
                    }
                  }
                }
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "example": 481903289
                    },
                    "name": {
                      "type": "string",
                      "example": "Product Name",
                      "maxLength": 60,
                      "description": "Maximum 60 characters. Longer values are rejected with 422 (\"Code for the item is too long\")."
                    },
                    "description": {
                      "type": "string",
                      "example": "Product description",
                      "maxLength": 200,
                      "description": "Maximum 200 characters and at most 20 lines. Longer values are rejected with 422."
                    },
                    "unit_price": {
                      "type": "number",
                      "example": 100
                    },
                    "unit": {
                      "type": "string",
                      "example": "piece",
                      "description": "Must be one of a fixed set of supported unit values, not a free-length string."
                    },
                    "quantity": {
                      "type": "number",
                      "example": 2
                    },
                    "tax": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "example": 756700
                        },
                        "name": {
                          "type": "string",
                          "example": "IVA23",
                          "maxLength": 255
                        },
                        "value": {
                          "type": "number",
                          "example": 23
                        }
                      }
                    },
                    "discount": {
                      "type": "number",
                      "example": 0
                    },
                    "subtotal": {
                      "type": "number",
                      "example": 180
                    },
                    "tax_amount": {
                      "type": "number",
                      "example": 41.4
                    },
                    "discount_amount": {
                      "type": "number",
                      "example": 0
                    },
                    "total": {
                      "type": "number",
                      "example": 221.4
                    },
                    "retention": {
                      "type": "number",
                      "example": 0
                    }
                  }
                }
              },
              "summary": {
                "type": "object",
                "properties": {
                  "sum": {
                    "type": "number",
                    "example": 200
                  },
                  "discount": {
                    "type": "number",
                    "example": 0
                  },
                  "before_taxes": {
                    "type": "number",
                    "example": 180
                  },
                  "taxes": {
                    "type": "number",
                    "example": 41.4
                  },
                  "total": {
                    "type": "number",
                    "example": 221.4
                  },
                  "currency": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "example": "Euro"
                      },
                      "code": {
                        "type": "string",
                        "example": "EUR"
                      },
                      "symbol": {
                        "type": "string",
                        "example": "€"
                      }
                    }
                  },
                  "retention": {
                    "type": "number",
                    "example": 0
                  },
                  "pay_progress": {
                    "type": "number",
                    "example": 0
                  },
                  "to_pay": {
                    "type": "number",
                    "example": 221.4
                  },
                  "total_paid": {
                    "type": "number",
                    "example": 0
                  },
                  "taxes_breakdown": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "category": {
                          "type": "string",
                          "example": "IVA23"
                        },
                        "items_value": {
                          "type": "number",
                          "example": 180
                        },
                        "tax_value": {
                          "type": "number",
                          "example": 41.4
                        }
                      }
                    }
                  },
                  "total_currency_rate": {
                    "type": "number",
                    "example": 0
                  },
                  "rate": {
                    "type": "number",
                    "example": 1
                  }
                }
              }
            }
          }
        }
      },
      "V3GuideRelatedDocumentsResponse": {
        "type": "object",
        "properties": {
          "related_documents": {
            "type": "array",
            "description": "List of documents related to the specified document.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "type": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "sequence_number": {
                  "type": "string"
                },
                "total": {
                  "type": "number"
                },
                "root_path": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "id": 12345,
                "type": "Shipping",
                "status": "final",
                "sequence_number": "2025/000123",
                "total": 123.45,
                "root_path": "shippings"
              }
            ]
          }
        }
      },
      "V3GuideTimelineResponse": {
        "type": "object",
        "properties": {
          "timeline": {
            "type": "array",
            "description": "List of timeline activities and events for the document.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "type": {
                  "type": "string"
                },
                "event": {
                  "type": "string",
                  "description": "Human-readable, translated label of the event (e.g. `Created`, `Finalized`, `Comment`), not a stable key. Do not branch on it; use `type` instead."
                },
                "author": {
                  "type": "string"
                },
                "message": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "author": {
                          "type": "string"
                        },
                        "auth_user": {
                          "type": "string"
                        }
                      }
                    },
                    "notification_type": {
                      "type": "string"
                    }
                  }
                },
                "to": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "date": {
                  "type": "string",
                  "format": "date-time"
                },
                "can_change": {
                  "type": "boolean"
                },
                "time_to_change": {
                  "type": "integer"
                }
              }
            },
            "example": [
              {
                "id": 2756411,
                "type": "Activity",
                "event": "Created",
                "author": "goncalo.correia@invoicexpress.com",
                "message": {
                  "data": {
                    "author": "goncalo.correia@invoicexpress.com",
                    "auth_user": "goncalo.correia@rupeal.com"
                  },
                  "notification_type": "guide"
                },
                "to": "goncalopcorreia@hotmail.com",
                "date": "2026-07-13T13:03:35+01:00",
                "can_change": false,
                "time_to_change": 0
              }
            ]
          }
        }
      },
      "V3UpdateGuideSummaryResponse": {
        "type": "object",
        "properties": {
          "summary": {
            "type": "object",
            "properties": {
              "sum": {
                "type": "number",
                "example": 19.99
              },
              "discount": {
                "type": "number",
                "example": 0
              },
              "before_taxes": {
                "type": "number",
                "example": 19.99
              },
              "taxes": {
                "type": "number",
                "example": 4.6
              },
              "total": {
                "type": "number",
                "example": 24.59
              },
              "currency": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Euro"
                  },
                  "code": {
                    "type": "string",
                    "example": "EUR"
                  },
                  "symbol": {
                    "type": "string",
                    "example": "€"
                  }
                }
              },
              "retention": {
                "type": "number",
                "example": 0
              },
              "pay_progress": {
                "type": "number",
                "example": 0
              },
              "to_pay": {
                "type": "number",
                "example": 24.59
              },
              "total_paid": {
                "type": "number",
                "example": 0
              },
              "taxes_breakdown": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "category": {
                      "type": "string"
                    },
                    "items_value": {
                      "type": "number"
                    },
                    "tax_value": {
                      "type": "number"
                    }
                  }
                },
                "example": [
                  {
                    "category": "IVA23",
                    "items_value": 10,
                    "tax_value": 2.3
                  },
                  {
                    "category": "IVA23",
                    "items_value": 9.99,
                    "tax_value": 2.3
                  }
                ]
              },
              "total_currency_rate": {
                "type": "number",
                "example": 0
              },
              "rate": {
                "type": "number",
                "example": 1
              }
            }
          }
        }
      },
      "V3ChangeGuideStateRequest": {
        "type": "object",
        "description": "The wrapper key must match the singular of the guide type used in the path (transport, shipping, or devolution) — using the wrong key returns a 422 (\"Invalid root element, expected ...\"). Shown here as \"transport\".",
        "required": [
          "transport"
        ],
        "properties": {
          "transport": {
            "type": "object",
            "required": [
              "state"
            ],
            "properties": {
              "state": {
                "type": "string",
                "description": "Target state event for guide documents (e.g. finalized, deleted, canceled).",
                "example": "finalized"
              },
              "message": {
                "type": "string",
                "description": "Cancellation reason. Required when `state` is `canceled`; if it is missing or empty the API returns 422 with \"The cancellation reason is a required field\" (text in the account's language). Ignored for the other states.",
                "example": "Goods were not shipped"
              }
            }
          }
        }
      },
      "V3ChangeGuideStateResponse": {
        "type": "object",
        "properties": {
          "transport": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "example": 257224199
              },
              "status": {
                "type": "string",
                "example": "final"
              },
              "archived": {
                "type": "boolean",
                "example": false
              },
              "type": {
                "type": "string",
                "example": "Shipping"
              },
              "sequence_number": {
                "type": "string",
                "example": "1/INVOICEXPRESSDEMO"
              },
              "inverted_sequence_number": {
                "type": "string",
                "example": "INVOICEXPRESSDEMO/1"
              },
              "sequence_id": {
                "type": "integer",
                "example": 5259465
              },
              "date": {
                "type": "string",
                "description": "dd/mm/yyyy",
                "example": "13/05/2026"
              },
              "due_date": {
                "type": "string",
                "description": "dd/mm/yyyy",
                "example": "13/06/2026"
              },
              "reference": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "maxLength": 255
              },
              "observations": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "description": "No enforced length limit (text column)."
              },
              "retention": {
                "type": [
                  "number",
                  "null"
                ],
                "example": null
              },
              "permalink": {
                "type": "string",
                "example": "https://web.invoicexpress.com/documents/abc123"
              },
              "saft_hash": {
                "type": "string",
                "example": "Xbsc",
                "description": "No enforced character limit (text column)."
              },
              "sum": {
                "type": "number",
                "example": 100
              },
              "discount": {
                "type": "number",
                "example": 0
              },
              "before_taxes": {
                "type": "number",
                "example": 100
              },
              "taxes": {
                "type": "number",
                "example": 23
              },
              "total": {
                "type": "number",
                "example": 123
              },
              "currency": {
                "type": "string",
                "example": "Euro"
              },
              "client": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer",
                    "example": 194666511
                  },
                  "name": {
                    "type": "string",
                    "example": "Test Client",
                    "maxLength": 100
                  }
                }
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "example": "Test Item",
                      "maxLength": 60,
                      "description": "Maximum 60 characters. Longer values are rejected with 422 (\"Code for the item is too long\")."
                    },
                    "description": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "example": null,
                      "maxLength": 200,
                      "description": "Maximum 200 characters and at most 20 lines. Longer values are rejected with 422."
                    },
                    "unit_price": {
                      "type": "string",
                      "example": "100.0"
                    },
                    "unit": {
                      "type": "string",
                      "example": "service",
                      "description": "Must be one of a fixed set of supported unit values, not a free-length string."
                    },
                    "quantity": {
                      "type": "string",
                      "example": "1.0"
                    },
                    "tax": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "example": 756700
                        },
                        "name": {
                          "type": "string",
                          "example": "IVA23",
                          "maxLength": 255
                        },
                        "value": {
                          "type": "number",
                          "example": 23
                        }
                      }
                    },
                    "discount": {
                      "type": "number",
                      "example": 0
                    },
                    "subtotal": {
                      "type": "number",
                      "example": 100
                    },
                    "tax_amount": {
                      "type": "number",
                      "example": 23
                    },
                    "discount_amount": {
                      "type": "number",
                      "example": 0
                    },
                    "total": {
                      "type": "number",
                      "example": 123
                    }
                  }
                }
              },
              "atcud": {
                "type": "string",
                "example": "N/D"
              }
            }
          }
        }
      },
      "V3EstimateListResponse": {
        "type": "object",
        "properties": {
          "estimates": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 257118662
                },
                "sequence_number": {
                  "type": "string",
                  "example": "INVOICEXPRESSDEMO/-"
                },
                "sequence": {
                  "type": "string",
                  "example": "INVOICEXPRESSDEMO"
                },
                "document_number": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": null
                },
                "type": {
                  "type": "string",
                  "example": "Quote"
                },
                "status": {
                  "type": "string",
                  "example": "draft"
                },
                "archived": {
                  "type": "boolean",
                  "example": false
                },
                "client_name": {
                  "type": "string",
                  "example": "Test Client API"
                },
                "reference": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "maxLength": 255,
                  "example": "PO-1234",
                  "description": "The document's free-text reference, the same value the `reference` filter searches. `null` when the document has none."
                },
                "date": {
                  "type": "string",
                  "example": "2026-05-11 00:00:00 +0100"
                },
                "valid_to": {
                  "type": "string",
                  "example": "2026-06-11 00:00:00 +0100"
                },
                "total": {
                  "type": "number",
                  "example": 123
                },
                "total_before_taxes": {
                  "type": "number",
                  "example": 100
                },
                "final_date": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": null
                },
                "token": {
                  "type": "string",
                  "example": "2571186625ad1072ab31349f6c7c6bd919c2547e43c965aa1"
                },
                "legacy_invoice_receipt_config": {
                  "type": [
                    "boolean",
                    "null"
                  ],
                  "example": false
                }
              }
            }
          },
          "totals": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "example": 1
              },
              "pages": {
                "type": "integer",
                "example": 1
              },
              "statuses": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "draft"
                ]
              },
              "total_due": {
                "type": "number",
                "example": 0
              },
              "total_due_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_overdue": {
                "type": "number",
                "example": 0
              },
              "total_overdue_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_drafts": {
                "type": "number",
                "example": 100
              },
              "total_drafts_with_taxes": {
                "type": "number",
                "example": 123
              },
              "total_accepted": {
                "type": "number",
                "example": 0
              },
              "total_accepted_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_refused": {
                "type": "number",
                "example": 0
              },
              "total_refused_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_canceled": {
                "type": "number",
                "example": 0
              },
              "total_canceled_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_before_taxes": {
                "type": "number",
                "example": 0
              },
              "total_taxes": {
                "type": "number",
                "example": 0
              },
              "total": {
                "type": "number",
                "example": 0
              }
            }
          }
        }
      },
      "V3CreateEstimateRequest": {
        "type": "object",
        "description": "The wrapper key matches the singular of the estimate type used in the path (quote, proforma, or fees_note) — shown here as \"quote\".",
        "properties": {
          "quote": {
            "type": "object",
            "required": [
              "date",
              "items"
            ],
            "properties": {
              "date": {
                "type": "string",
                "format": "date",
                "example": "2026-05-11"
              },
              "due_date": {
                "type": "string",
                "format": "date",
                "description": "Defaults to `date` when omitted or blank.",
                "example": "2026-06-11"
              },
              "reference": {
                "type": "string",
                "example": "PO-999",
                "maxLength": 255
              },
              "observations": {
                "type": "string",
                "example": "Services rendered",
                "description": "No enforced character limit (text column)."
              },
              "retention": {
                "type": "number",
                "example": 0
              },
              "tax_exemption": {
                "type": "string",
                "example": "M00",
                "maxLength": 255,
                "description": "255-character database column default (column `tax_exemption_code`); effectively an enum of AT exemption codes."
              },
              "sequence_id": {
                "type": "string",
                "example": "123456"
              },
              "manual_sequence_number": {
                "type": "string",
                "example": "001",
                "maxLength": 255,
                "description": "255-character database column default."
              },
              "client": {
                "type": "object",
                "description": "Optional. When omitted, the estimate is issued to Consumidor Final.",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Test Client API",
                    "maxLength": 100
                  },
                  "email": {
                    "type": "string",
                    "example": "client@example.com",
                    "maxLength": 254
                  },
                  "fiscal_id": {
                    "type": "string",
                    "example": "987654321",
                    "maxLength": 255
                  },
                  "address": {
                    "type": "string",
                    "example": "456 Client Street",
                    "description": "Street address as a flat string (not a nested object)."
                  },
                  "postal_code": {
                    "type": "string",
                    "example": "2000-002",
                    "maxLength": 255
                  },
                  "city": {
                    "type": "string",
                    "example": "Porto",
                    "maxLength": 255
                  },
                  "country": {
                    "type": "string",
                    "example": "Portugal",
                    "maxLength": 255,
                    "description": "Fiscal country of the client."
                  },
                  "address_country": {
                    "type": "string",
                    "example": "Portugal",
                    "description": "Country of the postal address, when different from the fiscal country; takes priority over `country` for the address."
                  }
                }
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "example": "Test Service",
                      "maxLength": 60,
                      "description": "Maximum 60 characters. Longer values are rejected with 422 (\"Code for the item is too long\")."
                    },
                    "description": {
                      "type": "string",
                      "example": "Service description",
                      "maxLength": 200,
                      "description": "Maximum 200 characters and at most 20 lines. Longer values are rejected with 422."
                    },
                    "unit_price": {
                      "type": "number",
                      "example": 100
                    },
                    "unit": {
                      "type": "string",
                      "example": "service"
                    },
                    "quantity": {
                      "type": "number",
                      "example": 1
                    },
                    "discount": {
                      "type": "number",
                      "example": 0
                    },
                    "tax": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "example": "IVA23"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "V3EstimateSummaryRequest": {
        "type": "object",
        "properties": {
          "id": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "257118662"
            ]
          }
        }
      },
      "V3EstimateSummaryResponse": {
        "type": "object",
        "properties": {
          "totals": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "example": 1
              },
              "pages": {
                "type": "integer",
                "example": 1
              },
              "statuses": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "draft"
                ]
              },
              "total_due": {
                "type": "number",
                "example": 0
              },
              "total_due_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_overdue": {
                "type": "number",
                "example": 0
              },
              "total_overdue_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_drafts": {
                "type": "number",
                "example": 100
              },
              "total_drafts_with_taxes": {
                "type": "number",
                "example": 123
              },
              "total_accepted": {
                "type": "number",
                "example": 0
              },
              "total_accepted_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_refused": {
                "type": "number",
                "example": 0
              },
              "total_refused_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_canceled": {
                "type": "number",
                "example": 0
              },
              "total_canceled_with_taxes": {
                "type": "number",
                "example": 0
              },
              "total_before_taxes": {
                "type": "number",
                "example": 0
              },
              "total_taxes": {
                "type": "number",
                "example": 0
              },
              "total": {
                "type": "number",
                "example": 0
              }
            }
          }
        }
      },
      "V3UpdateSummaryEstimateRequest": {
        "type": "object",
        "description": "The wrapper key matches the singular of the estimate type used in the path (quote, proforma, or fees_note) — shown here as \"quote\". Using the wrong key returns a 422 (\"No quote element provided\", with the expected key name).",
        "properties": {
          "quote": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string",
                "format": "date",
                "example": "2026-05-11"
              },
              "due_date": {
                "type": "string",
                "format": "date",
                "example": "2026-06-11"
              },
              "retention": {
                "type": "number",
                "example": 0
              },
              "global_discount": {
                "type": "object",
                "properties": {
                  "value_type": {
                    "type": "string",
                    "example": "percentage"
                  },
                  "value": {
                    "type": "number",
                    "example": 10
                  }
                }
              },
              "items": {
                "type": "array",
                "description": "Estimate items.",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "maxLength": 60,
                      "description": "Maximum 60 characters. Longer values are rejected with 422 (\"Code for the item is too long\")."
                    },
                    "description": {
                      "type": "string",
                      "maxLength": 200,
                      "description": "Maximum 200 characters and at most 20 lines. Longer values are rejected with 422."
                    },
                    "unit_price": {
                      "type": "number"
                    },
                    "unit": {
                      "type": "string"
                    },
                    "quantity": {
                      "type": "number"
                    },
                    "discount": {
                      "type": "number"
                    },
                    "retention": {
                      "type": "number"
                    },
                    "tax": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "value": {
                          "type": "number"
                        }
                      }
                    }
                  }
                },
                "example": [
                  {
                    "name": "Service A",
                    "description": "Consulting services",
                    "unit_price": 100,
                    "unit": "hour",
                    "quantity": 2,
                    "tax": {
                      "name": "IVA23",
                      "value": 23
                    },
                    "discount": 0,
                    "retention": 0
                  }
                ]
              }
            }
          }
        }
      },
      "V3UpdateEstimateSummaryResponse": {
        "type": "object",
        "properties": {
          "summary": {
            "type": "object",
            "properties": {
              "sum": {
                "type": "number",
                "example": 200
              },
              "discount": {
                "type": "number",
                "example": 0
              },
              "before_taxes": {
                "type": "number",
                "example": 200
              },
              "taxes": {
                "type": "number",
                "example": 46
              },
              "total": {
                "type": "number",
                "example": 246
              },
              "currency": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Euro"
                  },
                  "code": {
                    "type": "string",
                    "example": "EUR"
                  },
                  "symbol": {
                    "type": "string",
                    "example": "€"
                  }
                }
              },
              "retention": {
                "type": "number",
                "example": 0
              },
              "pay_progress": {
                "type": "number",
                "example": 0
              },
              "to_pay": {
                "type": "number",
                "example": 246
              },
              "total_paid": {
                "type": "number",
                "example": 0
              },
              "taxes_breakdown": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "category": {
                      "type": "string"
                    },
                    "items_value": {
                      "type": "number"
                    },
                    "tax_value": {
                      "type": "number"
                    }
                  }
                },
                "example": [
                  {
                    "category": "IVA23",
                    "items_value": 200,
                    "tax_value": 46
                  }
                ]
              },
              "total_currency_rate": {
                "type": "number",
                "example": 0
              },
              "rate": {
                "type": "number",
                "example": 1
              }
            }
          }
        }
      },
      "V3EstimateDocumentResponse": {
        "type": "object",
        "properties": {
          "quote": {
            "type": "object",
            "description": "Wrapper key matches the singular of the requested estimate type (quote, proforma, or fees_note).",
            "properties": {
              "id": {
                "type": "integer",
                "example": 257118662
              },
              "status": {
                "type": "string",
                "example": "draft"
              },
              "archived": {
                "type": "boolean",
                "example": false
              },
              "type": {
                "type": "string",
                "example": "Quote"
              },
              "sequence_number": {
                "type": "string",
                "example": "draft"
              },
              "inverted_sequence_number": {
                "type": "string",
                "example": "draft"
              },
              "sequence_id": {
                "type": "integer",
                "example": 5259462
              },
              "atcud": {
                "type": "string",
                "example": "N/A"
              },
              "date": {
                "type": "string",
                "format": "date",
                "example": "2026-05-11"
              },
              "due_date": {
                "type": "string",
                "format": "date",
                "example": "2026-06-11"
              },
              "reference": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "maxLength": 255
              },
              "observations": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "description": "No enforced character limit (text column)."
              },
              "token": {
                "type": "string",
                "example": "2571186625ad1072ab31349f6c7c6bd919c2547e43c965aa1"
              },
              "permalink": {
                "type": "string",
                "example": "https://web.invoicexpress.com/documents/2571186625ad1072ab31349f6c7c6bd919c2547e43c965aa1?language=pt"
              },
              "retention": {
                "type": "number",
                "example": 0
              },
              "global_discount": {
                "$ref": "#/components/schemas/V3DocumentGlobalDiscount"
              },
              "owner_invoice_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": null
              },
              "raw_owner_invoice": {
                "$ref": "#/components/schemas/V3DocumentRawOwnerInvoice"
              },
              "currency": {
                "$ref": "#/components/schemas/V3DocumentCurrency"
              },
              "auto_add_related_document": {
                "type": "boolean",
                "example": false
              },
              "qr_code": {
                "$ref": "#/components/schemas/V3DocumentQrCodeField"
              },
              "digital_signed": {
                "$ref": "#/components/schemas/V3DocumentDigitalSignedField"
              },
              "include_payment_reference": {
                "$ref": "#/components/schemas/V3DocumentIncludePaymentReferenceField"
              },
              "auto_send_invoice_from_estimate": {
                "type": "boolean",
                "description": "Conditional — never present on API-key requests. Same conditions as `include_payment_reference`; reflects the account's \"auto-send invoice from estimate\" preference.",
                "example": false
              },
              "account": {
                "type": "object",
                "properties": {
                  "organization_name": {
                    "type": "string",
                    "example": "invoicexpress"
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "detail": {
                        "type": "string",
                        "example": "Avenida Duque D'Avila, Saldanha"
                      },
                      "postal_code": {
                        "type": "string",
                        "example": "1500-555"
                      },
                      "city": {
                        "type": "string",
                        "example": "Lisbon"
                      },
                      "country": {
                        "type": "string",
                        "example": "Portugal"
                      },
                      "translated_country": {
                        "type": "string",
                        "description": "Country name in the request language.",
                        "example": "Portugal"
                      }
                    }
                  },
                  "email": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "user@example.com"
                  },
                  "phone": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": null
                  },
                  "phone_country_code": {
                    "$ref": "#/components/schemas/V3DocumentPhoneCountryCode"
                  },
                  "phone_indicative_printed": {
                    "$ref": "#/components/schemas/V3DocumentPhoneIndicativePrinted"
                  },
                  "website": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": null
                  },
                  "footer": {
                    "$ref": "#/components/schemas/V3DocumentAccountFooter"
                  },
                  "fiscal_id": {
                    "type": "string",
                    "example": "999999990"
                  },
                  "logo": {
                    "type": "string",
                    "example": ""
                  },
                  "bank_data": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "example": "IBAN"
                        },
                        "value": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "example": null
                        }
                      }
                    }
                  }
                }
              },
              "client": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer",
                    "example": 194634837
                  },
                  "name": {
                    "type": "string",
                    "example": "Test Client API",
                    "maxLength": 100
                  },
                  "email": {
                    "type": "string",
                    "example": "",
                    "maxLength": 254
                  },
                  "phone": {
                    "type": "string",
                    "description": "Empty string when unset.",
                    "example": ""
                  },
                  "phone_country_code": {
                    "$ref": "#/components/schemas/V3DocumentPhoneCountryCode"
                  },
                  "mobile": {
                    "type": "string",
                    "description": "Empty string when unset.",
                    "example": ""
                  },
                  "mobile_country_code": {
                    "$ref": "#/components/schemas/V3DocumentPhoneCountryCode"
                  },
                  "fiscal_id": {
                    "type": "string",
                    "example": "",
                    "maxLength": 255
                  },
                  "country": {
                    "type": "string",
                    "description": "Display name of the client's country; empty when unset.",
                    "example": ""
                  },
                  "translated_country": {
                    "type": "string",
                    "description": "Client's fiscal country name in the request language.",
                    "example": ""
                  },
                  "address": {
                    "type": "object",
                    "properties": {
                      "detail": {
                        "type": "string",
                        "example": "",
                        "maxLength": 255
                      },
                      "postal_code": {
                        "type": "string",
                        "example": "",
                        "maxLength": 255
                      },
                      "city": {
                        "type": "string",
                        "example": "",
                        "maxLength": 255
                      },
                      "address_country": {
                        "type": "string",
                        "example": "PT"
                      }
                    }
                  }
                }
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "example": 472475279
                    },
                    "name": {
                      "type": "string",
                      "example": "Test Service",
                      "maxLength": 60,
                      "description": "Maximum 60 characters. Longer values are rejected with 422 (\"Code for the item is too long\")."
                    },
                    "description": {
                      "type": "string",
                      "example": "",
                      "maxLength": 200,
                      "description": "Maximum 200 characters and at most 20 lines. Longer values are rejected with 422."
                    },
                    "unit_price": {
                      "type": "number",
                      "example": 100
                    },
                    "unit": {
                      "type": "string",
                      "example": "service"
                    },
                    "quantity": {
                      "type": "number",
                      "example": 1
                    },
                    "tax": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "example": 756700
                        },
                        "name": {
                          "type": "string",
                          "example": "IVA23"
                        },
                        "value": {
                          "type": "number",
                          "example": 23
                        }
                      }
                    },
                    "discount": {
                      "type": "number",
                      "example": 0
                    },
                    "subtotal": {
                      "type": "number",
                      "example": 100
                    },
                    "tax_amount": {
                      "type": "number",
                      "example": 23
                    },
                    "discount_amount": {
                      "type": "number",
                      "example": 0
                    },
                    "total": {
                      "type": "number",
                      "example": 123
                    },
                    "retention": {
                      "type": "number",
                      "example": 0
                    }
                  }
                }
              },
              "summary": {
                "type": "object",
                "properties": {
                  "sum": {
                    "type": "number",
                    "example": 100
                  },
                  "discount": {
                    "type": "number",
                    "example": 0
                  },
                  "before_taxes": {
                    "type": "number",
                    "example": 100
                  },
                  "taxes": {
                    "type": "number",
                    "example": 23
                  },
                  "total": {
                    "type": "number",
                    "example": 123
                  },
                  "currency": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "example": "Euro"
                      },
                      "code": {
                        "type": "string",
                        "example": "EUR"
                      },
                      "symbol": {
                        "type": "string",
                        "example": "€"
                      }
                    }
                  },
                  "retention": {
                    "type": "number",
                    "example": 0
                  },
                  "pay_progress": {
                    "type": "number",
                    "example": 0
                  },
                  "to_pay": {
                    "type": "number",
                    "example": 123
                  },
                  "total_paid": {
                    "type": "number",
                    "example": 0
                  },
                  "taxes_breakdown": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "category": {
                          "type": "string",
                          "example": "IVA23"
                        },
                        "items_value": {
                          "type": "number",
                          "example": 100
                        },
                        "tax_value": {
                          "type": "number",
                          "example": 23
                        }
                      }
                    }
                  },
                  "total_currency_rate": {
                    "type": "number",
                    "example": 0
                  },
                  "rate": {
                    "type": "number",
                    "example": 1
                  }
                }
              }
            }
          }
        }
      },
      "V3UpdateEstimateRequest": {
        "type": "object",
        "description": "The wrapper key matches the singular of the estimate type used in the path (quote, proforma, or fees_note) — shown here as \"quote\". The `items` array replaces the whole item set of the document. A missing wrapper returns 422 \"No quote element provided\" (with the expected key name); a missing or empty `items` array returns 422 \"No items element provided\".",
        "required": [
          "quote"
        ],
        "properties": {
          "proprietary_uid": {
            "type": "string",
            "description": "Optional caller-side identifier, sent at the top level (outside the wrapper)."
          },
          "quote": {
            "type": "object",
            "required": [
              "items"
            ],
            "properties": {
              "date": {
                "type": "string",
                "format": "date",
                "example": "2026-05-11"
              },
              "due_date": {
                "type": "string",
                "format": "date",
                "example": "2026-06-11"
              },
              "reference": {
                "type": "string",
                "example": "PO-999",
                "maxLength": 255
              },
              "observations": {
                "type": "string",
                "example": "Services rendered"
              },
              "retention": {
                "type": "number",
                "example": 0
              },
              "tax_exemption": {
                "type": "string",
                "example": "M00",
                "maxLength": 255
              },
              "sequence_id": {
                "type": "string",
                "example": "123456"
              },
              "manual_sequence_number": {
                "type": "string",
                "example": "001",
                "maxLength": 255
              },
              "global_discount": {
                "type": "object",
                "properties": {
                  "value_type": {
                    "type": "string",
                    "enum": [
                      "percentage",
                      "absolute"
                    ],
                    "example": "percentage"
                  },
                  "value": {
                    "type": "number",
                    "example": 10
                  }
                }
              },
              "client": {
                "description": "Optional on update. When sent, it must identify a client by `id`, `name` or `code`; an `id` not owned by the account (with no `name`/`code` to fall back on) returns 422 \"No client was found with the id provided.\"",
                "allOf": [
                  {
                    "$ref": "#/components/schemas/client"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "example": 12345
                      },
                      "code": {
                        "type": "string",
                        "example": "CLI-001"
                      }
                    }
                  }
                ]
              },
              "items": {
                "$ref": "#/components/schemas/items"
              }
            }
          }
        }
      },
      "V3EstimateNewResponse": {
        "type": "object",
        "description": "Defaults and choices for building a new estimate of the requested type. Nothing is created. The body has no wrapper key.",
        "properties": {
          "due_date_choices": {
            "type": "array",
            "description": "Due-date options in days. The one matching the client's (or else the account's) payment days is flagged `selected`; a value not in the list replaces the last (\"Other\") entry.",
            "items": {
              "type": "object",
              "properties": {
                "value": {
                  "oneOf": [
                    {
                      "type": "integer"
                    },
                    {
                      "type": "string"
                    }
                  ],
                  "description": "Days, or \"custom\" for the Other entry."
                },
                "description": {
                  "type": "string"
                },
                "selected": {
                  "type": "boolean"
                }
              }
            },
            "example": [
              {
                "value": 0,
                "description": "Immediately"
              },
              {
                "value": 15,
                "description": "15 days"
              },
              {
                "value": 30,
                "description": "30 days",
                "selected": true
              },
              {
                "value": "custom",
                "description": "Other"
              }
            ]
          },
          "exemption_reasons": {
            "type": "array",
            "description": "VAT exemption reasons; the client's (or account's) code is flagged `selected`.",
            "items": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "example": "M07"
                },
                "reason": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "selected": {
                  "type": "boolean"
                }
              }
            }
          },
          "sequences": {
            "type": "array",
            "description": "Sequences of this estimate type available for issuing (only AT-registered ones for Portuguese accounts). The account's current serie is flagged `selected`. When there are none, a single disabled placeholder entry with `id` null is returned (\"Choose a registered Sequence\", or \"Choose a Sequence\" for foreign accounts).",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "example": 5259462
                },
                "serie": {
                  "type": "string",
                  "example": "2026"
                },
                "selected": {
                  "type": "boolean"
                },
                "disabled": {
                  "type": "boolean"
                }
              }
            }
          },
          "currencies": {
            "type": "array",
            "description": "Available currencies; the client's currency is flagged `selected`.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 1
                },
                "name": {
                  "type": "string",
                  "example": "Euro"
                },
                "code": {
                  "type": "string",
                  "example": "EUR"
                },
                "symbol": {
                  "type": "string",
                  "example": "€"
                },
                "selected": {
                  "type": "boolean"
                }
              }
            }
          },
          "retention": {
            "type": "array",
            "description": "Withholding-tax options. The first entry (\"Not applicable\") has `id` and `value` null.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "value": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "description": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "id": null,
                "value": null,
                "description": "Not applicable"
              }
            ]
          },
          "remarks": {
            "type": "string",
            "description": "Default observations (client's, else account's) followed by the exemption reason text, if any."
          },
          "include_payment_reference": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Null unless the plan has MB references, a payment provider is configured and the type supports payment references; then the account's estimate setting."
          },
          "has_configured_payment_service": {
            "type": "boolean",
            "example": false
          },
          "auto_send_invoice_from_estimate": {
            "type": "boolean",
            "example": false
          },
          "taxes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 1
                },
                "name": {
                  "type": "string",
                  "example": "IVA23"
                },
                "region": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "PT"
                },
                "code": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": "NOR"
                },
                "value": {
                  "type": "number",
                  "example": 23
                },
                "default_tax": {
                  "type": "integer",
                  "enum": [
                    0,
                    1
                  ],
                  "example": 1
                }
              }
            }
          },
          "client": {
            "type": "object",
            "description": "Present only when a known `client_id` query parameter is sent.",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "fiscal_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "address": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "postal_code": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "city": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "country": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      },
      "V3EstimateIndexRequest": {
        "type": "object",
        "description": "Same filters as the GET list operation, sent as a JSON body. Range filters are nested objects (`{\"date\":{\"from\":...,\"to\":...}}`).",
        "properties": {
          "page": {
            "type": "integer",
            "example": 1
          },
          "per_page": {
            "type": "integer",
            "example": 10,
            "description": "Page size (default 10). Aliases: `items_per_page`, `page_items`."
          },
          "language": {
            "type": "string",
            "example": "pt"
          },
          "sort": {
            "type": "string",
            "example": "date"
          },
          "sort_order": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "example": "desc"
          },
          "text": {
            "type": "string",
            "example": "John Doe"
          },
          "reference": {
            "type": "string",
            "example": "PO-999"
          },
          "archived": {
            "type": "boolean"
          },
          "non_archived": {
            "type": "boolean"
          },
          "fuid": {
            "type": "string"
          },
          "batch_id": {
            "type": "string"
          },
          "id": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "except_id": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "type": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "Quote",
                "Proforma",
                "FeesNote"
              ]
            }
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "draft",
                "sent",
                "accepted",
                "refused",
                "canceled",
                "deleted"
              ]
            }
          },
          "client_id": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "serie_name": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "date": {
            "$ref": "#/components/schemas/V3EstimateIndexRange"
          },
          "valid_to": {
            "$ref": "#/components/schemas/V3EstimateIndexRange"
          },
          "total_before_taxes": {
            "$ref": "#/components/schemas/V3EstimateIndexRange"
          },
          "total_with_taxes": {
            "$ref": "#/components/schemas/V3EstimateIndexRange"
          }
        },
        "example": {
          "page": 1,
          "per_page": 10,
          "status": [
            "draft"
          ],
          "date": {
            "from": "2026-04-01",
            "to": "2026-04-30"
          }
        }
      },
      "V3EstimateRelatedDocumentsResponse": {
        "type": "object",
        "properties": {
          "related_documents": {
            "type": "array",
            "description": "List of documents related to the specified estimate.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "type": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "sequence_number": {
                  "type": "string"
                },
                "total": {
                  "type": "number"
                },
                "root_path": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "id": 12345,
                "type": "Quote",
                "status": "final",
                "sequence_number": "2025/000123",
                "total": 221.4,
                "root_path": "quotes"
              }
            ]
          }
        }
      },
      "V3EstimateTimelineResponse": {
        "type": "object",
        "properties": {
          "timeline": {
            "type": "array",
            "description": "List of timeline activities and events for the estimate document.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "type": {
                  "type": "string"
                },
                "event": {
                  "type": "string",
                  "description": "Human-readable, translated label of the event (e.g. `Created`, `Finalized`, `Comment`), not a stable key. Do not branch on it; use `type` instead."
                },
                "author": {
                  "type": "string"
                },
                "message": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "author": {
                          "type": "string",
                          "example": "user@invoicexpress.com"
                        }
                      }
                    }
                  }
                },
                "to": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": null
                },
                "date": {
                  "type": "string",
                  "format": "date-time",
                  "example": "2026-05-12T15:51:13+01:00"
                },
                "can_change": {
                  "type": "boolean"
                },
                "time_to_change": {
                  "type": "integer"
                }
              }
            },
            "example": [
              {
                "id": 195861,
                "type": "Activity",
                "event": "Created",
                "author": "user@invoicexpress.com",
                "message": {
                  "data": {
                    "author": "user@invoicexpress.com"
                  }
                },
                "to": null,
                "date": "2026-05-12T15:51:13+01:00",
                "can_change": true,
                "time_to_change": 14
              }
            ]
          }
        }
      },
      "V3EstimateError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "example": "Date can't be blank"
                }
              }
            }
          }
        }
      },
      "V3ChangeEstimateStateRequest": {
        "type": "object",
        "description": "The wrapper key must match the singular of the estimate type used in the path (quote, proforma, or fees_note) — using the wrong key returns a 422 (\"Invalid root element, expected ...\"). Shown here as \"quote\".",
        "required": [
          "quote"
        ],
        "properties": {
          "quote": {
            "type": "object",
            "required": [
              "state"
            ],
            "properties": {
              "state": {
                "type": "string",
                "description": "Target state event. `finalized` moves a draft to sent, `accept` / `refuse` mark it accepted / refused, `canceled` cancels it and `deleted` deletes a draft.",
                "enum": [
                  "finalized",
                  "accept",
                  "refuse",
                  "canceled",
                  "deleted"
                ],
                "example": "finalized"
              },
              "message": {
                "type": "string",
                "description": "Cancellation reason. Required when `state` is `canceled`; if it is missing or empty the API returns 422 with \"The cancellation reason is a required field\" (text in the account's language). Ignored for the other states.",
                "example": "Client withdrew the request"
              }
            }
          }
        }
      },
      "V3ChangeEstimateStateResponse": {
        "type": "object",
        "properties": {
          "quote": {
            "type": "object",
            "description": "Wrapper key matches the singular of the requested estimate type (quote, proforma, or fees_note).",
            "properties": {
              "id": {
                "type": "integer",
                "example": 257224130
              },
              "status": {
                "type": "string",
                "example": "final",
                "description": "A finalized document is returned as `final` here; the list endpoint returns the same status as `sent`."
              },
              "archived": {
                "type": "boolean",
                "example": false
              },
              "type": {
                "type": "string",
                "example": "Quote"
              },
              "sequence_number": {
                "type": "string",
                "example": "1/INVOICEXPRESSDEMO"
              },
              "inverted_sequence_number": {
                "type": "string",
                "example": "INVOICEXPRESSDEMO/1"
              },
              "sequence_id": {
                "type": "integer",
                "example": 5259462
              },
              "date": {
                "type": "string",
                "description": "dd/mm/yyyy",
                "example": "13/05/2026"
              },
              "due_date": {
                "type": "string",
                "description": "dd/mm/yyyy",
                "example": "13/06/2026"
              },
              "reference": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "maxLength": 255
              },
              "observations": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "description": "No enforced character limit (text column)."
              },
              "retention": {
                "type": [
                  "number",
                  "null"
                ],
                "example": null
              },
              "permalink": {
                "type": "string",
                "example": "https://web.invoicexpress.com/documents/abc123"
              },
              "saft_hash": {
                "type": "string",
                "example": "Xbsc",
                "description": "No enforced character limit (text column)."
              },
              "sum": {
                "type": "number",
                "example": 100
              },
              "discount": {
                "type": "number",
                "example": 0
              },
              "before_taxes": {
                "type": "number",
                "example": 100
              },
              "taxes": {
                "type": "number",
                "example": 23
              },
              "total": {
                "type": "number",
                "example": 123
              },
              "currency": {
                "type": "string",
                "example": "Euro"
              },
              "client": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "integer",
                    "example": 194666511
                  },
                  "name": {
                    "type": "string",
                    "example": "Test Client",
                    "maxLength": 100
                  }
                }
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "example": "Test Item",
                      "maxLength": 60,
                      "description": "Maximum 60 characters. Longer values are rejected with 422 (\"Code for the item is too long\")."
                    },
                    "description": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "example": null,
                      "maxLength": 200,
                      "description": "Maximum 200 characters and at most 20 lines. Longer values are rejected with 422."
                    },
                    "unit_price": {
                      "type": "string",
                      "example": "100.0"
                    },
                    "unit": {
                      "type": "string",
                      "example": "service"
                    },
                    "quantity": {
                      "type": "string",
                      "example": "1.0"
                    },
                    "tax": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "example": 756700
                        },
                        "name": {
                          "type": "string",
                          "example": "IVA23"
                        },
                        "value": {
                          "type": "number",
                          "example": 23
                        }
                      }
                    },
                    "discount": {
                      "type": "number",
                      "example": 0
                    },
                    "subtotal": {
                      "type": "number",
                      "example": 100
                    },
                    "tax_amount": {
                      "type": "number",
                      "example": 23
                    },
                    "discount_amount": {
                      "type": "number",
                      "example": 0
                    },
                    "total": {
                      "type": "number",
                      "example": 123
                    }
                  }
                }
              },
              "atcud": {
                "type": "string",
                "example": "N/D"
              }
            }
          }
        }
      },
      "V3SequenceListResponse": {
        "type": "object",
        "properties": {
          "sequences": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 5259451
                },
                "serie_name": {
                  "type": "string",
                  "example": "INVOICEXPRESSDEMO",
                  "maxLength": 35
                },
                "status": {
                  "type": "string",
                  "example": "active"
                },
                "is_default": {
                  "type": "boolean",
                  "example": true
                },
                "register_status": {
                  "type": "string",
                  "example": "not_registered"
                },
                "register_type": {
                  "type": "string",
                  "example": "normal"
                },
                "state_change_in_progress": {
                  "type": "boolean",
                  "example": false
                },
                "customize_path": {
                  "type": "string",
                  "example": "series_configurations/148306/new?series_name=INVOICEXPRESSDEMO"
                },
                "archived": {
                  "type": "boolean",
                  "example": false,
                  "description": "`true` when the série is archived."
                }
              }
            }
          },
          "totals": {
            "type": "object",
            "properties": {
              "pages": {
                "type": "integer",
                "example": 1
              },
              "total": {
                "type": "integer",
                "example": 1,
                "description": "Number of séries matching the filters (`text`, `archived`) across every page."
              }
            }
          },
          "offer_demo_cleanup": {
            "type": "boolean",
            "description": "`true` only when the account has the demo série (`INVOICEXPRESSDEMO`) and no other série yet, i.e. when creating the first real série can also delete the demo one (`delete_demo_series`).",
            "example": false
          }
        }
      },
      "V3ArchiveSequenceRequest": {
        "type": "object",
        "required": [
          "sequence"
        ],
        "properties": {
          "sequence": {
            "type": "object",
            "required": [
              "serie_name"
            ],
            "properties": {
              "serie_name": {
                "type": "string",
                "example": "SERIE2026",
                "description": "Name of the série. A série that does not exist answers 404."
              }
            }
          }
        }
      },
      "V3CreateSequenceRequest": {
        "type": "object",
        "required": [
          "sequence"
        ],
        "properties": {
          "sequence": {
            "type": "object",
            "required": [
              "serie_name"
            ],
            "properties": {
              "serie_name": {
                "type": "string",
                "example": "SERIE2026",
                "minLength": 1,
                "maxLength": 35
              },
              "set_as_default": {
                "type": "boolean",
                "default": false,
                "description": "When `true` (or the string \"true\"), the new série becomes the account's default série.",
                "example": false
              },
              "create_and_registry": {
                "type": "boolean",
                "default": false,
                "description": "When `true` (or the string \"true\"), the série is also registered with the tax authority (AT) right after it is created. The response is then `202` instead of `201`.",
                "example": false
              },
              "delete_demo_series": {
                "type": "boolean",
                "default": false,
                "description": "When `true`, the demo série is deleted as part of the operation. Only a real `true` (or the string \"true\") opts in; any other value means `false`.",
                "example": false
              }
            }
          }
        }
      },
      "V3SequenceAsyncResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "status_endpoint": {
            "type": "string",
            "description": "Relative path and query string to poll with `GET /api/v3/sequences/create_status`. Its `account_id` is an encrypted account token, not the numeric account id — pass it back unchanged.",
            "example": "/create_status?account_id=7117e09c4cd4ba7b05b2cc10e34d8684&serie_name=SERIE2026&create_and_registry=false&sequence_already_exists=false"
          }
        }
      },
      "V3SequencesByNameResponse": {
        "type": "object",
        "properties": {
          "series": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "INVOICEXPRESSDEMO",
              "SERIE2026"
            ]
          }
        }
      },
      "V3SequenceCollectionResponse": {
        "type": "object",
        "properties": {
          "sequences": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "type": "string",
                  "example": "invoices"
                },
                "register_type": {
                  "type": "string",
                  "example": ""
                },
                "register_status": {
                  "type": "string",
                  "example": ""
                },
                "validation_code": {
                  "type": "string",
                  "example": "",
                  "maxLength": 100,
                  "description": "AT validation code. When present it is 8-100 characters; empty while the series is not registered."
                },
                "state_change_in_progress": {
                  "type": "boolean",
                  "example": false
                },
                "error": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": null
                },
                "last_result": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "example": null
                }
              }
            }
          },
          "register_status": {
            "type": "string",
            "example": ""
          },
          "sequence_status": {
            "type": "string",
            "example": "active"
          }
        }
      },
      "V3SequenceCreateStatusResponse": {
        "type": "object",
        "description": "Status of a série creation/registration. A failed operation is still\nanswered with HTTP 200 and `success: false`.\n\n`data` takes one of these shapes:\n- while processing (HTTP 202): `{completed, total}` progress counters;\n- finished creation without registration: `{}`;\n- successful registration of an existing series\n  (`sequence_already_exists=true`): `{}`;\n- finished registration: `{last_result, errors}` (`errors` holds the AT\n  rejection when there is one);\n- registration that could not be confirmed in time:\n  `{last_result: \"unknown\", timed_out: true}` — the registration may\n  still complete.",
        "properties": {
          "operation_status": {
            "type": "string",
            "enum": [
              "processing",
              "finished"
            ],
            "example": "finished"
          },
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "anyOf": [
              {
                "type": "object",
                "title": "Progress",
                "properties": {
                  "completed": {
                    "type": "integer",
                    "example": 3
                  },
                  "total": {
                    "type": "integer",
                    "example": 12
                  }
                }
              },
              {
                "type": "object",
                "title": "Registration result",
                "properties": {
                  "last_result": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "success"
                  },
                  "errors": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "message_code": {
                        "type": "string"
                      },
                      "invalid_reason": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "message": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    }
                  }
                }
              },
              {
                "type": "object",
                "title": "Timed out",
                "properties": {
                  "last_result": {
                    "type": "string",
                    "enum": [
                      "unknown"
                    ],
                    "example": "unknown"
                  },
                  "timed_out": {
                    "type": "boolean",
                    "enum": [
                      true
                    ],
                    "example": true
                  }
                }
              }
            ],
            "example": {}
          }
        }
      },
      "V3SetDefaultSequenceRequest": {
        "type": "object",
        "properties": {
          "sequence": {
            "type": "object",
            "required": [
              "serie_name"
            ],
            "properties": {
              "serie_name": {
                "type": "string",
                "example": "INVOICEXPRESSDEMO",
                "minLength": 1,
                "maxLength": 35
              }
            }
          }
        }
      },
      "V3RegisterSequenceRequest": {
        "type": "object",
        "required": [
          "sequence"
        ],
        "properties": {
          "sequence": {
            "type": "object",
            "description": "The série is identified by its name, not by a sequence id. All the sequences of that série that still need registering are sent to the AT.",
            "required": [
              "serie_name"
            ],
            "properties": {
              "serie_name": {
                "type": "string",
                "example": "INVOICEXPRESSDEMO",
                "description": "Name of the série to register."
              },
              "delete_demo_series": {
                "type": "boolean",
                "default": false,
                "description": "When `true`, the demo série is deleted as part of the registration. Only a real `true` (or the string \"true\") opts in; any other value means `false`.",
                "example": false
              }
            }
          }
        }
      },
      "V3SequenceValidationError": {
        "type": "object",
        "description": "The série could not be created or registered. `code` is `invalid_serie` (invalid name), `serie_already_exists` (name already in use), `unknown_error` (any other validation failure) or `registration_error` (the AT registration could not be started; returned with HTTP 500). `message` follows the account language.",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string"
                },
                "code": {
                  "type": "string",
                  "enum": [
                    "invalid_serie",
                    "serie_already_exists",
                    "unknown_error",
                    "registration_error"
                  ]
                }
              }
            },
            "example": [
              {
                "message": "Validation failed: Serie has already been taken",
                "code": "serie_already_exists"
              }
            ]
          }
        }
      },
      "V3SequenceMissingRootError": {
        "type": "object",
        "description": "The `sequence` root object is missing or empty.",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "param is missing or the value is empty or invalid: sequence"
              }
            ]
          }
        }
      },
      "V3RegisteredSeriesResponse": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "example": [
          "2023",
          "2024"
        ]
      },
      "V3ClientListResponse": {
        "type": "object",
        "properties": {
          "clients": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3ClientListItem"
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "total_entries": {
                "type": "integer",
                "example": 18
              },
              "current_page": {
                "type": "integer",
                "example": 1
              },
              "total_pages": {
                "type": "integer",
                "example": 2
              },
              "per_page": {
                "type": "integer",
                "example": 10
              }
            }
          }
        }
      },
      "V3ClientResponse": {
        "type": "object",
        "properties": {
          "client": {
            "$ref": "#/components/schemas/V3ClientObject"
          }
        }
      },
      "V3CreateClientRequest": {
        "type": "object",
        "required": [
          "client"
        ],
        "properties": {
          "client": {
            "allOf": [
              {
                "$ref": "#/components/schemas/V3ClientWritableFields"
              },
              {
                "type": "object",
                "required": [
                  "name"
                ]
              }
            ]
          }
        }
      },
      "V3UpdateClientRequest": {
        "type": "object",
        "required": [
          "client"
        ],
        "description": "Partial update. Only the keys you send are changed; no field inside `client` is required.",
        "properties": {
          "client": {
            "allOf": [
              {
                "$ref": "#/components/schemas/V3ClientWritableFields"
              },
              {
                "type": "object",
                "properties": {
                  "use_account_settings": {
                    "type": "boolean",
                    "example": true,
                    "description": "Update only (ignored on create). When `true`, after the other fields are saved the client's `tax_exemption_code`, `payment_mechanism`, `language`, `currency_id`, `payment_days`, `send_options` and `observations` are cleared, so the account defaults apply."
                  }
                }
              }
            ]
          }
        }
      },
      "V3ClientSuggestionsResponse": {
        "type": "object",
        "properties": {
          "clients": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3ClientSuggestionItem"
            }
          }
        }
      },
      "V3ClientBalanceResponse": {
        "type": "object",
        "properties": {
          "currency": {
            "type": "object",
            "description": "The client's own currency. Both fields are `null` when the client has no currency set (no fallback to the account currency).",
            "properties": {
              "symbol": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "€"
              },
              "code": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "EUR"
              }
            }
          },
          "initial_balance": {
            "type": "object",
            "properties": {
              "value": {
                "type": "number",
                "example": 0
              },
              "created_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date",
                "description": "The date of the initial balance (not when it was recorded). `null` when the client has no initial balance.",
                "example": "2024-01-01"
              },
              "observation": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              }
            }
          },
          "balance": {
            "type": "object",
            "properties": {
              "with_vat": {
                "type": "number",
                "example": 123
              }
            }
          },
          "overdue_balance": {
            "type": "object",
            "properties": {
              "with_vat": {
                "type": "number",
                "example": 123
              }
            }
          },
          "remaining_balance": {
            "type": "object",
            "properties": {
              "total": {
                "type": "number",
                "example": 0
              },
              "value": {
                "type": "number",
                "example": 0
              }
            }
          }
        }
      },
      "V3ClientListItem": {
        "type": "object",
        "description": "Simplified client object returned in list responses.",
        "properties": {
          "id": {
            "type": "integer",
            "example": 191880320
          },
          "name": {
            "type": "string",
            "example": "John Doe",
            "maxLength": 100
          },
          "fiscal_id": {
            "type": [
              "string",
              "null"
            ],
            "example": "508025338",
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "example": "john@example.com",
            "maxLength": 254
          },
          "balance": {
            "type": [
              "string",
              "null"
            ],
            "example": "2774.38",
            "description": "Latest client balance, as a decimal string. `null` when the client has no balance record yet."
          },
          "created_at": {
            "type": "string",
            "example": "2025-01-23T10:22:33+00:00"
          },
          "code": {
            "type": "string",
            "example": "EUR",
            "description": "ISO code of the **account's** currency (the same for every client in the list). This is not the client's own `code`."
          },
          "archived_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "example": null,
            "description": "When the client was archived, or `null` when it is not archived. List rows carry only this field; `archived` and `can_be_deleted` are returned by show, create and update."
          }
        }
      },
      "V3InitialBalanceRequest": {
        "type": "object",
        "required": [
          "initial_balance"
        ],
        "properties": {
          "initial_balance": {
            "type": "object",
            "required": [
              "value",
              "date"
            ],
            "properties": {
              "value": {
                "type": "number",
                "minimum": 0,
                "example": 123,
                "description": "Must be `>= 0` and `>=` the sum of the client's regularizations. Omitting it fails with HTTP 500."
              },
              "date": {
                "type": "string",
                "format": "date",
                "example": "2024-01-01",
                "description": "Must be on or before the date of the client's first regularization and on or before the date of the client's first non-draft document."
              },
              "observation": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              }
            }
          }
        }
      },
      "V3InitialBalanceResponse": {
        "type": "object",
        "properties": {
          "initial_balance": {
            "$ref": "#/components/schemas/V3InitialBalanceObject"
          }
        }
      },
      "V3RegularizationListResponse": {
        "type": "object",
        "properties": {
          "regularization": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3RegularizationItem"
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "total_entries": {
                "type": "integer",
                "example": 0
              },
              "current_page": {
                "type": "integer",
                "example": 1
              },
              "total_pages": {
                "type": "integer",
                "example": 0
              },
              "per_page": {
                "type": "integer",
                "example": 10
              }
            }
          }
        }
      },
      "V3CreateRegularizationRequest": {
        "type": "object",
        "required": [
          "regularization"
        ],
        "properties": {
          "regularization": {
            "type": "object",
            "required": [
              "date"
            ],
            "properties": {
              "value": {
                "type": "number",
                "example": 123.45,
                "description": "Must be less than or equal to the client's remaining balance (initial balance minus existing regularizations)."
              },
              "date": {
                "type": "string",
                "format": "date",
                "example": "2023-08-24",
                "description": "Required. Cannot be before the date of the client's initial balance."
              },
              "observation": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              }
            }
          }
        }
      },
      "V3RegularizationResponse": {
        "type": "object",
        "properties": {
          "regularization": {
            "$ref": "#/components/schemas/V3RegularizationItem"
          }
        }
      },
      "V3SendOpenAccountLinkMailRequest": {
        "type": "object",
        "required": [
          "send_open_account_link_mail"
        ],
        "properties": {
          "send_open_account_link_mail": {
            "type": "object",
            "required": [
              "client"
            ],
            "properties": {
              "client": {
                "type": "object",
                "required": [
                  "email",
                  "save"
                ],
                "description": "Required. Omitting `client` fails with HTTP 500.",
                "properties": {
                  "email": {
                    "type": "string",
                    "example": "john.doe@invoicexpress.com",
                    "description": "Required (`client's email is required`)."
                  },
                  "save": {
                    "type": "integer",
                    "example": 0,
                    "description": "Required (`client save is required`). `1`/`true` stores `email` as the client's preferred contact email."
                  }
                }
              },
              "cc": {
                "type": "string",
                "example": "john.doe@invoicexpress.com"
              },
              "bcc": {
                "type": "string",
                "example": "john.doe@invoicexpress.com"
              },
              "notification_type": {
                "type": "string",
                "example": "open_account_link"
              },
              "send_email_copy": {
                "type": "integer",
                "example": 0
              },
              "body": {
                "type": "string",
                "example": "Some email body with a link"
              },
              "subject": {
                "type": "string",
                "example": "Something important"
              }
            }
          }
        }
      },
      "V3CreateTreasuryMovementRequest": {
        "type": "object",
        "required": [
          "treasury_movement"
        ],
        "properties": {
          "treasury_movement": {
            "type": "object",
            "required": [
              "movement_type",
              "date"
            ],
            "properties": {
              "movement_type": {
                "type": "string",
                "enum": [
                  "Payment",
                  "Reimbursement",
                  "InitialBalance",
                  "Regularization"
                ],
                "example": "Payment",
                "description": "Any other value is rejected with HTTP 422."
              },
              "value": {
                "type": "number",
                "minimum": 0,
                "example": 123.45,
                "description": "For `Payment`, must not exceed the client's open balance (with VAT). For `Reimbursement`, must not exceed the settled balance that can be reimbursed (of `document_id` when sent, otherwise of all the client's documents)."
              },
              "date": {
                "type": "string",
                "format": "date",
                "example": "2023-04-28",
                "description": "Required — omitting it fails with HTTP 500. A value that cannot be parsed as a date is replaced by today's date."
              },
              "payment_method": {
                "type": "string",
                "example": "MB"
              },
              "document_id": {
                "type": "integer",
                "example": 987654,
                "description": "`Reimbursement` only: restrict the reimbursement to this settled document."
              },
              "serie": {
                "type": "string",
                "example": "2023",
                "description": "`Payment` only: passed to the receipts issued for the paid documents. Not stored on the movement."
              },
              "observation": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "description": "`Payment` only: used as the note of the receipts issued for the paid documents. Not stored on the movement."
              }
            }
          }
        }
      },
      "V3TreasuryMovementResponse": {
        "type": "object",
        "properties": {
          "treasury_movement": {
            "$ref": "#/components/schemas/V3TreasuryMovementObject"
          }
        }
      },
      "V3AccountResponse": {
        "type": "object",
        "properties": {
          "account": {
            "$ref": "#/components/schemas/V3AccountObject"
          }
        }
      },
      "V3CreateAccountRequest": {
        "type": "object",
        "required": [
          "email",
          "password",
          "account"
        ],
        "properties": {
          "email": {
            "type": "string",
            "example": "john.doe@example.com",
            "maxLength": 255
          },
          "password": {
            "type": "string",
            "example": "Fa8aVs.B!~k+"
          },
          "password_confirmation": {
            "type": "string",
            "description": "Ignored. The server always uses `password` as the confirmation.",
            "example": "Fa8aVs.B!~k+"
          },
          "account": {
            "type": "object",
            "required": [
              "organization_name",
              "fiscal_id",
              "address",
              "postal_code",
              "city"
            ],
            "properties": {
              "organization_name": {
                "type": "string",
                "example": "Strong Security",
                "maxLength": 100,
                "description": "Values longer than 100 characters are rejected with HTTP 422."
              },
              "fiscal_id": {
                "type": "string",
                "example": "123456789",
                "maxLength": 255,
                "description": "Required. Missing or blank is rejected with 422 (\"VAT Number can't be blank\")."
              },
              "address": {
                "type": "string",
                "example": "Avenida da Liberdade",
                "maxLength": 210,
                "description": "Required. Missing or blank is rejected with 422 (\"Address can't be blank\"); values longer than 210 characters are rejected with HTTP 422."
              },
              "postal_code": {
                "type": "string",
                "example": "1250-144",
                "maxLength": 255,
                "description": "Required. Missing or blank is rejected with 422 (\"Postal code can't be blank\")."
              },
              "city": {
                "type": "string",
                "example": "Lisboa",
                "maxLength": 50,
                "description": "Required. Missing or blank is rejected with 422 (\"City can't be blank\"); values longer than 50 characters are rejected with HTTP 422."
              },
              "language": {
                "type": "string",
                "example": "pt",
                "maxLength": 4
              }
            }
          }
        }
      },
      "V3CreateAccountResponse": {
        "type": "object",
        "description": "Returned by both `POST /api/v3/accounts` and\n`POST /api/v3/accounts/create_already_user`. The shape depends on how the\nrequest is made:\n\n- **API request** (an `api_key` query parameter is sent, or there is no\n  `X-WEB-REQUEST` header): `success`, `token`, `url` and `api_key`.\n- **Web request** (`X-WEB-REQUEST` header and no `api_key`): `success`,\n  `token` and `redirect`.\n",
        "required": [
          "success",
          "token"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "token": {
            "type": "string",
            "example": "a41f5ef81ad1a93f6e362ef94818ef6497f857745346dba064d081229102e28593818d4496d70fdfe436195a4eed6ed813cd560e043c8fd9aa5889b044d47848"
          },
          "url": {
            "type": "string",
            "example": "https://strongsecurity.app.invoicexpress.com",
            "description": "API requests only. Home URL of the new account."
          },
          "api_key": {
            "type": "string",
            "example": "d8117512267a1d84ebb64c65b6294b0719e78134",
            "description": "API requests only. API key of the user on the new account."
          },
          "redirect": {
            "type": "string",
            "example": "https://strongsecurity.app.invoicexpress.com",
            "description": "Web requests only. Home URL of the new account (replaces `url` and `api_key`)."
          }
        }
      },
      "V3UpdateAccountRequest": {
        "type": "object",
        "required": [
          "account"
        ],
        "properties": {
          "retroactive_communication_option": {
            "type": "string",
            "enum": [
              "only_this_year",
              "this_year_and_last_year"
            ],
            "example": "only_this_year",
            "description": "Optional. When the account ends up with `at_communication_type` `auto` (and is not a SAF-T big account), the documents of the chosen years are communicated to the AT retroactively. Any other value communicates nothing retroactively."
          },
          "account": {
            "type": "object",
            "description": "Required. An empty body (no `account` key and no top-level account field) returns 422 \"Param is missing\"; top-level account fields are wrapped into `account` automatically. Only the fields sent are changed.",
            "properties": {
              "address_country": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "PT",
                "description": "ISO country code of the address."
              },
              "billing_address_country": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "PT",
                "description": "ISO country code of the billing address."
              },
              "billing_data_confirmed": {
                "type": "boolean",
                "example": true,
                "description": "Marks the billing data as confirmed. Once confirmed it is not changed again."
              },
              "capital_social": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "5000 EUR",
                "maxLength": 255
              },
              "conservatoria": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Lisboa",
                "maxLength": 255
              },
              "currency_id": {
                "type": "integer",
                "example": 1
              },
              "decimal_marker": {
                "type": "string",
                "example": ",",
                "maxLength": 255
              },
              "email": {
                "type": "string",
                "example": "billing@example.com",
                "maxLength": 255
              },
              "fiscal_region": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "description": "Cleared (set to null) when `billing_country_id` is sent with a country other than 1 and no `fiscal_region` is sent."
              },
              "invoice_footer": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Company registered in Lisbon.",
                "maxLength": 200,
                "description": "Values longer than 200 characters are rejected with HTTP 422."
              },
              "observations": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "maxLength": 400,
                "description": "Values longer than 400 characters are rejected with HTTP 422."
              },
              "payment_mechanism": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "maxLength": 255
              },
              "tax_exemption_code": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "M07",
                "maxLength": 255
              },
              "tax_location_id": {
                "type": "integer",
                "example": 1,
                "description": "When different from 1 and sent together with `fiscal_id`, the VAT number is validated for that country; an invalid one returns 422 \"VAT Number is invalid\"."
              },
              "address": {
                "type": "string",
                "example": "Avenida Duque D'Ávila 46 – 3ºA",
                "maxLength": 210,
                "description": "Values longer than 210 characters are rejected with HTTP 422."
              },
              "at_communication_type": {
                "type": "string",
                "example": "auto",
                "maxLength": 255
              },
              "at_subuser": {
                "type": "string",
                "example": "599999993/1",
                "maxLength": 255
              },
              "at_password": {
                "type": "string",
                "example": "123456",
                "maxLength": 255,
                "description": "Checked against the AT before saving; rejected credentials return 422 \"The tax authority rejected the at_subuser/at_password combination\"."
              },
              "bank_data1": {
                "type": "string",
                "example": "PT50 123456789",
                "maxLength": 255
              },
              "bank_data2": {
                "type": "string",
                "example": "1234",
                "maxLength": 255
              },
              "bank_data3": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "maxLength": 255
              },
              "billing_address": {
                "type": "string",
                "example": "Avenida Duque D'Ávila 46 – 3ºA",
                "maxLength": 255
              },
              "billing_city": {
                "type": "string",
                "example": "Porto",
                "maxLength": 255
              },
              "billing_country_id": {
                "type": "integer",
                "example": 1
              },
              "billing_email": {
                "type": "string",
                "example": "test@example.com",
                "maxLength": 255
              },
              "billing_fiscal_id": {
                "type": "string",
                "example": "999999990",
                "maxLength": 255
              },
              "billing_organization_name": {
                "type": "string",
                "example": "Invoice Xpress",
                "maxLength": 255
              },
              "billing_postal_code": {
                "type": "string",
                "example": "1011-123",
                "maxLength": 255
              },
              "city": {
                "type": "string",
                "example": "Lisboa",
                "maxLength": 50,
                "description": "Values longer than 50 characters are rejected with HTTP 422."
              },
              "fiscal_id": {
                "type": "string",
                "example": "508000111",
                "maxLength": 255
              },
              "iva_caixa": {
                "type": "boolean",
                "example": true
              },
              "language": {
                "type": "string",
                "example": "pt",
                "maxLength": 4
              },
              "organization_name": {
                "type": "string",
                "example": "Invoice Xpress",
                "maxLength": 100,
                "description": "Values longer than 100 characters are rejected with HTTP 422."
              },
              "postal_code": {
                "type": "string",
                "example": "1011-123",
                "maxLength": 255
              }
            }
          }
        }
      },
      "V3YearsDocumentsResponse": {
        "type": "object",
        "properties": {
          "years": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "example": [
              2026,
              2025,
              2024,
              2023
            ]
          }
        }
      },
      "V3ExportResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "We'll send you an email when it's done to: info@test.com."
          }
        }
      },
      "V3BillingHistoryResponse": {
        "type": "object",
        "properties": {
          "billing_history": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3BillingHistoryItem"
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "total_entries": {
                "type": "integer",
                "example": 0
              },
              "current_page": {
                "type": "integer",
                "example": 1
              },
              "total_pages": {
                "type": "integer",
                "example": 0
              },
              "per_page": {
                "type": "integer",
                "example": 10
              }
            }
          }
        }
      },
      "V3CreateAlreadyUserRequest": {
        "type": "object",
        "description": "Credentials of an existing InvoiceXpress user plus the data of the new account. The user is authenticated with `email` and `password`; an unknown email or a wrong password returns 422 \"Invalid email or password\".",
        "required": [
          "email",
          "password",
          "account"
        ],
        "properties": {
          "email": {
            "type": "string",
            "example": "john.doe@example.com",
            "maxLength": 255,
            "description": "Email (login) of the existing user."
          },
          "password": {
            "type": "string",
            "example": "Fa8aVs.B!~k+",
            "description": "Current password of the existing user."
          },
          "account": {
            "$ref": "#/components/schemas/account"
          }
        }
      },
      "V3ATActiveCommunicationResponse": {
        "type": "object",
        "properties": {
          "account": {
            "type": "object",
            "properties": {
              "fiscal_id": {
                "type": "string",
                "example": "999999990",
                "maxLength": 255
              },
              "at_user": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "legacy_credentials_present": {
                "type": "boolean",
                "example": true
              },
              "account_credentials_present": {
                "type": "boolean",
                "example": false
              }
            }
          }
        }
      },
      "V3ATCommunicationRequest": {
        "type": "object",
        "required": [
          "at_communication"
        ],
        "properties": {
          "at_communication": {
            "type": "object",
            "description": "Required. A missing `at_communication` key returns 500.",
            "properties": {
              "at_subuser": {
                "type": "string",
                "example": "123456789/3",
                "maxLength": 255,
                "description": "Required unless `communication_type` is `manual`. Must contain `/`. Omitting it (with a non-`manual` `communication_type`) fails with 500 (\"undefined method 'include?' for nil\"); only an empty string gives 422."
              },
              "at_password": {
                "type": [
                  "string",
                  "integer"
                ],
                "example": 1234567,
                "description": "Required unless `communication_type` is `manual`. Checked against the AT."
              },
              "communication_type": {
                "type": "string",
                "enum": [
                  "auto",
                  "guides",
                  "manual",
                  "portal_at"
                ],
                "example": "auto"
              },
              "retroactive_communication_option": {
                "type": "string",
                "enum": [
                  "only_this_year",
                  "this_year_and_last_year"
                ],
                "example": "only_this_year",
                "description": "Optional. When the account ends up with `communication_type` `auto` (and is not a SAF-T big account), the documents of the chosen years are communicated to the AT retroactively. Any other value communicates nothing retroactively."
              }
            }
          }
        }
      },
      "V3ATCommunicationHistoryResponse": {
        "type": "object",
        "properties": {
          "communication_history": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3ATCommunicationHistoryItem"
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "total_entries": {
                "type": "integer",
                "example": 0
              },
              "current_page": {
                "type": "integer",
                "example": 1
              },
              "total_pages": {
                "type": "integer",
                "example": 0
              },
              "per_page": {
                "type": "integer",
                "example": 10
              }
            }
          }
        }
      },
      "V3AccountSettingsResponse": {
        "type": "object",
        "properties": {
          "currency_separator": {
            "type": "string",
            "example": ","
          },
          "currency_symbol": {
            "type": "string",
            "example": "€"
          },
          "currency_code": {
            "type": "string",
            "example": "EUR"
          },
          "language": {
            "type": "string",
            "example": "en",
            "maxLength": 4
          },
          "sequence_number_mode": {
            "type": "string",
            "example": "auto"
          },
          "batch_import_rule": {
            "type": "boolean",
            "example": true
          },
          "first_document": {
            "type": "boolean",
            "example": true
          },
          "logo_url": {
            "type": "string",
            "example": "https://aws-s3-url-logo.com"
          },
          "account_name": {
            "type": "string",
            "example": "Company Test"
          }
        }
      },
      "V3AccountUsersResponse": {
        "type": "object",
        "properties": {
          "users": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3AccountUserItem"
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "total_entries": {
                "type": "integer",
                "example": 3
              },
              "current_page": {
                "type": "integer",
                "example": 1
              },
              "total_pages": {
                "type": "integer",
                "example": 1
              },
              "per_page": {
                "type": "integer",
                "example": 10
              }
            }
          }
        }
      },
      "V3CreateAccountUserRequest": {
        "type": "object",
        "required": [
          "user"
        ],
        "properties": {
          "user": {
            "type": "object",
            "required": [
              "email"
            ],
            "properties": {
              "email": {
                "type": "string",
                "example": "john.doe@invoicexpress.com",
                "maxLength": 255
              },
              "role": {
                "type": "string",
                "enum": [
                  "administrator",
                  "contributor",
                  "contributor_guides"
                ],
                "example": "contributor",
                "description": "Optional. A missing or unknown role gives the user the `contributor` role."
              }
            }
          }
        }
      },
      "V3UpdateAccountUserRequest": {
        "type": "object",
        "required": [
          "user"
        ],
        "properties": {
          "user": {
            "type": "object",
            "required": [
              "role"
            ],
            "description": "Required. A JSON body without the `user` key is wrapped into `user` automatically, so it fails with 422 \"Role is invalid\" rather than 500.",
            "properties": {
              "role": {
                "type": "string",
                "enum": [
                  "administrator",
                  "contributor",
                  "contributor_guides"
                ],
                "example": "administrator",
                "description": "New role of the user on the account. A missing or unknown role returns 422 \"Role is invalid\"."
              }
            }
          }
        }
      },
      "V3AccountUserResponse": {
        "type": "object",
        "properties": {
          "user": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "example": 147436
              },
              "email": {
                "type": "string",
                "example": "tito.reis@visma.com",
                "maxLength": 255
              },
              "phone_country_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": 1
              },
              "role": {
                "type": "string",
                "example": "contributor"
              }
            }
          }
        }
      },
      "V3DocumentCustomizationResponse": {
        "type": "object",
        "description": "Full account document customization profile returned by GET (or the customization of one série, with `serie_name`). When there is no customization to return, every field except `has_series_configuration` is an empty string (`has_series_configuration` stays a boolean, normally `false`).",
        "properties": {
          "has_series_configuration": {
            "type": "boolean",
            "example": false,
            "description": "Whether the série given in `serie_name` has its own customization (instead of using the account's). Always `false` without `serie_name`."
          },
          "organization_name": {
            "type": [
              "string",
              "null"
            ],
            "example": "invoicexpress",
            "maxLength": 100,
            "description": "Values longer than 100 characters are rejected with HTTP 422."
          },
          "fiscal_id": {
            "type": [
              "string",
              "null"
            ],
            "example": "999999990",
            "maxLength": 255
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "example": "Avenida Duque D'Avila, Saldanha",
            "maxLength": 210,
            "description": "Values longer than 210 characters are rejected with HTTP 422."
          },
          "postal_code": {
            "type": [
              "string",
              "null"
            ],
            "example": "1500-555",
            "maxLength": 255
          },
          "city": {
            "type": [
              "string",
              "null"
            ],
            "example": "Lisbon",
            "maxLength": 50,
            "description": "Values longer than 50 characters are rejected with HTTP 422."
          },
          "country": {
            "type": [
              "string",
              "null"
            ],
            "example": "Portugal"
          },
          "share_capital": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "register_office": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "logo_url": {
            "type": [
              "string",
              "null"
            ],
            "example": ""
          },
          "remarks": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "footer": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "document_copies": {
            "type": "integer",
            "example": 1
          },
          "payment_days": {
            "type": "integer",
            "example": 0
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "example": "tito.reis@visma.com",
            "maxLength": 255
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255
          },
          "website": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255
          },
          "phone_country_id": {
            "type": [
              "integer",
              "null"
            ],
            "example": 1
          },
          "tax_exemption_code": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255
          },
          "bank_data_type_1": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255
          },
          "bank_data_value_1": {
            "type": [
              "string",
              "null"
            ],
            "example": "",
            "maxLength": 255
          },
          "bank_data_type_2": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255
          },
          "bank_data_value_2": {
            "type": [
              "string",
              "null"
            ],
            "example": "",
            "maxLength": 255
          },
          "bank_data_type_3": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255
          },
          "bank_data_value_3": {
            "type": [
              "string",
              "null"
            ],
            "example": "",
            "maxLength": 255
          }
        }
      },
      "V3UpdateDocumentCustomizationRequest": {
        "type": "object",
        "description": "**Full replace, not a partial update.** Fields are sent flat (no wrapper key).\nEvery field listed below that is missing or blank in the request is set to\n`null` — send the complete customization every time, including the values\nyou want to keep.\n\nWithout `serie_name` the account-level customization is replaced: email,\nphone, website, phone_country_id, tax_exemption_code, remarks, footer,\ndocument_copies, payment_days and the three bank_data_type/bank_data_value\npairs.\n\nWith `serie_name` only the customization of that série is replaced: footer,\nemail, phone, website, phone_country_id and the three bank data pairs (the\nother fields are ignored). If all of them are blank and no `file` is sent,\nthe série is unlinked from its customization and falls back to the\naccount's data — unless that customization has a logo: then it is not\nunlinked; its fields are cleared and the logo is kept.\n\nTo upload a logo, send the request as `multipart/form-data` with the image\nin `file`.\n",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "example": "billing@example.com",
            "description": "Must be a valid email address (\"email_invalid\")."
          },
          "phone": {
            "type": "string",
            "example": "213456789"
          },
          "website": {
            "type": "string",
            "example": "https://example.com"
          },
          "phone_country_id": {
            "type": "integer",
            "example": 1,
            "description": "Id of the phone calling code (see Phone Calling Codes)."
          },
          "tax_exemption_code": {
            "type": "string",
            "example": "M07",
            "description": "Default tax exemption code. Account level only."
          },
          "remarks": {
            "type": "string",
            "maxLength": 400,
            "example": "Thank you for your business.",
            "description": "Default document observations. Maximum 400 characters (\"observations_too_long\"). Account level only."
          },
          "footer": {
            "type": "string",
            "maxLength": 200,
            "example": "Company registered in Lisbon.",
            "description": "Document footer. Maximum 200 characters (\"invoice_footer_too_long\")."
          },
          "document_copies": {
            "type": "integer",
            "example": 2,
            "description": "Number of document copies. Account level only."
          },
          "payment_days": {
            "type": "integer",
            "example": 15,
            "description": "Default payment days. Account level only."
          },
          "bank_data_type_1": {
            "type": "string",
            "example": "IBAN",
            "description": "When set, `bank_data_value_1` is required (\"bank_data1_blank\")."
          },
          "bank_data_value_1": {
            "type": "string",
            "example": "PT50000201231234567890154"
          },
          "bank_data_type_2": {
            "type": "string",
            "example": "SWIFT",
            "description": "When set, `bank_data_value_2` is required (\"bank_data2_blank\")."
          },
          "bank_data_value_2": {
            "type": "string",
            "example": "CGDIPTPL"
          },
          "bank_data_type_3": {
            "type": "string",
            "example": "",
            "description": "When set, `bank_data_value_3` is required (\"bank_data3_blank\")."
          },
          "bank_data_value_3": {
            "type": "string",
            "example": ""
          },
          "serie_name": {
            "type": "string",
            "example": "2026",
            "description": "Name of a série of the account. When present, the customization of that série is replaced instead of the account's."
          },
          "file": {
            "type": "string",
            "format": "binary",
            "description": "Logo image (multipart/form-data only). PNG, JPEG or JPG, at most 200 KB and 1000x1000 pixels; otherwise 422 \"The image is not valid. It must be in 'png', 'jpeg' or 'jpg' format, and have a maximum of 1000 pixels.\""
          }
        }
      },
      "V3UpdateDocumentCustomizationError": {
        "type": "object",
        "description": "Validation errors. Each `error` is `<field>_<error type>`.",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "observations_too_long"
              },
              {
                "error": "bank_data1_blank"
              }
            ]
          }
        }
      },
      "V3SuccessResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "V3UpdateDocumentCustomizationResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "logo_error": {
            "type": "string",
            "enum": [
              "logo_upload_failed"
            ],
            "description": "Present only when the logo could not be stored. The other fields of the request were saved and the previous logo was kept; send the logo again.",
            "example": "logo_upload_failed"
          }
        }
      },
      "V3AccountCredentialRequest": {
        "type": "object",
        "required": [
          "account_credential"
        ],
        "properties": {
          "account_credential": {
            "type": "object",
            "description": "`context` and `type` are always required. `username` and `password` are required on PUT, and on POST unless `use_legacy_credentials` is `true`. The `username` must start with the account's NIF (format `NIF/subuser`).",
            "required": [
              "context",
              "type"
            ],
            "properties": {
              "username": {
                "type": "string",
                "example": "123456789/1",
                "maxLength": 255
              },
              "password": {
                "type": "string",
                "example": "test123",
                "description": "Stored encrypted (AES-256-CBC, Base64-encoded), so the usable plaintext length is meaningfully shorter than the underlying column width. No exact limit is published."
              },
              "context": {
                "type": "string",
                "enum": [
                  "Invoices",
                  "Guides",
                  "Sequences"
                ],
                "example": "Sequences"
              },
              "type": {
                "type": "string",
                "enum": [
                  "AT"
                ],
                "example": "AT"
              },
              "use_legacy_credentials": {
                "type": "boolean",
                "default": false,
                "description": "POST only. When `true`, the credentials are copied from the account's existing (legacy) AT communication details instead of `username`/`password`, which may then be omitted. Fails with 422 when the account has no legacy credentials or already has credentials.",
                "example": false
              }
            }
          }
        }
      },
      "V3AccountCredentialCreatedResponse": {
        "type": "object",
        "description": "Body returned on success. `http_code` is `created` for POST (HTTP 201) and `ok` for PUT (HTTP 200).",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "http_code": {
            "type": "string",
            "enum": [
              "created",
              "ok"
            ],
            "example": "created"
          }
        }
      },
      "V3AccountCredentialErrorResponse": {
        "type": "object",
        "description": "The AT credentials were rejected. `key` is `subuser_unmatch_nif` when `username` does not start with the account's NIF, and `at_invalid_credentials` when the AT refused them.",
        "properties": {
          "errors": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string",
                "enum": [
                  "at_invalid_credentials",
                  "subuser_unmatch_nif"
                ],
                "example": "at_invalid_credentials"
              },
              "message": {
                "type": "string",
                "enum": [
                  "Invalid Credentials",
                  "AT subuser unmatch NIF"
                ],
                "example": "Invalid Credentials"
              }
            }
          }
        }
      },
      "V3AccountCredentialMessageError": {
        "type": "object",
        "description": "Request-level error. Messages: `Missing required params.`, `param is missing or the value is empty or invalid: account_credential`, `User doesn't have fiscal id associated` (rarely reachable: an account without a NIF fails the `subuser_unmatch_nif` check first), `No active at credentials present` (422); `Already has credentials for this context` (409, POST); `No credentials to update` (404, PUT).",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "Missing required params."
              }
            ]
          }
        }
      },
      "V3CollectionAlertResponse": {
        "type": "object",
        "properties": {
          "collection_alert": {
            "$ref": "#/components/schemas/V3CollectionAlertObject"
          }
        }
      },
      "V3CreateCollectionAlertRequest": {
        "type": "object",
        "required": [
          "collection_alert"
        ],
        "properties": {
          "client_id": {
            "type": "integer",
            "example": 1,
            "description": "Optional. When sent, the configuration of that client is created/updated instead of the account's. An unknown client returns 404 \"Client not found\"."
          },
          "collection_alert": {
            "type": "object",
            "description": "An enum field with a value outside its list returns 422.",
            "properties": {
              "frequency": {
                "type": "string",
                "enum": [
                  "disabled",
                  "biweekly",
                  "weekly",
                  "first_week",
                  "last_week"
                ],
                "example": "biweekly"
              },
              "weekday": {
                "type": "string",
                "enum": [
                  "monday",
                  "tuesday",
                  "wednesday",
                  "thursday",
                  "friday"
                ],
                "example": "monday"
              },
              "period": {
                "type": "string",
                "enum": [
                  "morning",
                  "afternoon"
                ],
                "example": "morning"
              },
              "due": {
                "type": "string",
                "enum": [
                  "before_overdue",
                  "after_overdue"
                ],
                "example": "before_overdue"
              },
              "email": {
                "type": "boolean",
                "example": true
              },
              "sms": {
                "type": "boolean",
                "example": false
              },
              "email_template": {
                "type": "string",
                "example": "This is an email\nwith a break line"
              },
              "sms_template": {
                "type": "string",
                "example": ""
              },
              "replicate": {
                "type": "boolean",
                "example": false,
                "description": "Account level (no `client_id`): when `true`, every client-level\nconfiguration is deleted, so all clients follow the account\nconfiguration.\n\nClient level (`PUT` with `client_id`): when `true`, the client's\nown configuration is deleted (the client falls back to the\naccount configuration) and the other fields are ignored; the\nresponse is `{\"collection_alert\": {\"client_has_email\": ...}}`.\n"
              }
            }
          }
        }
      },
      "V3ImportBatchMetadata": {
        "type": "object",
        "properties": {
          "batch_metadata_id": {
            "type": "integer",
            "example": 123
          },
          "batch_name": {
            "type": [
              "string",
              "null"
            ],
            "example": "My import batch"
          },
          "status": {
            "type": "string",
            "enum": [
              "started",
              "mapping",
              "validating",
              "validated",
              "configured",
              "importing",
              "sending_email",
              "completed",
              "failed"
            ],
            "example": "validated"
          },
          "date": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-08T15:19:10.902Z"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-08T15:19:10.902Z"
          },
          "doc_type": {
            "type": [
              "string",
              "null"
            ],
            "example": "invoices"
          },
          "doc_status": {
            "type": [
              "string",
              "null"
            ],
            "example": "draft"
          },
          "sequence_id": {
            "type": [
              "integer",
              "null"
            ],
            "example": 12345
          },
          "sequence": {
            "type": [
              "string",
              "null"
            ],
            "example": "FAT 2024"
          },
          "send_by_email": {
            "type": "boolean",
            "example": false
          },
          "header": {
            "type": [
              "string",
              "null"
            ],
            "description": "Stored as a string: the `exclude_first_line` value sent to process, as Rails casts it (JSON `true` → \"t\", `false` → \"f\"). Null until the CSV is processed, and still null after processing when `exclude_first_line` was not sent.",
            "example": "t"
          },
          "separator": {
            "type": [
              "string",
              "null"
            ],
            "example": ","
          },
          "filename": {
            "type": "string",
            "example": "import.csv"
          },
          "exemption_reason_id": {
            "type": [
              "integer",
              "null"
            ],
            "example": null
          },
          "discount_type": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          }
        }
      },
      "V3ImportJobResponse": {
        "type": "object",
        "properties": {
          "import": {
            "type": "object",
            "properties": {
              "job_id": {
                "type": "string",
                "example": "abc123def456"
              },
              "message": {
                "type": "string",
                "example": "Import job enqueued"
              }
            }
          }
        }
      },
      "V3ImportTemplateResponse": {
        "type": "object",
        "properties": {
          "template": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "example": "https://s3.amazonaws.com/bucket/template.csv?signed=..."
              }
            }
          }
        }
      },
      "V3ProcessRequest": {
        "type": "object",
        "required": [
          "process"
        ],
        "description": "The `process` wrapper is required (missing or empty → 400), even when sending only defaults.",
        "properties": {
          "process": {
            "type": "object",
            "properties": {
              "separator": {
                "type": "string",
                "enum": [
                  "auto",
                  ",",
                  "comma",
                  ";",
                  "semicolon",
                  "\t",
                  "tab",
                  "|",
                  "pipe"
                ],
                "default": "auto",
                "description": "Column separator. `auto` detects it from the first line. The value is lowercased before matching (e.g. `TAB` works as `tab`).",
                "example": "auto"
              },
              "exclude_first_line": {
                "type": "boolean",
                "example": false
              }
            }
          }
        }
      },
      "V3ValidateJobResponse": {
        "type": "object",
        "properties": {
          "validate": {
            "type": "object",
            "properties": {
              "job_id": {
                "type": "string",
                "example": "abc123"
              },
              "message": {
                "type": "string",
                "example": "Validation job enqueued"
              }
            }
          }
        }
      },
      "V3ValidationStatusResponse": {
        "type": "object",
        "properties": {
          "validate": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean",
                "example": true
              },
              "status": {
                "type": "string",
                "enum": [
                  "completed",
                  "validated"
                ],
                "description": "`completed` when the result comes from the finished validation job; `validated` when the job status has expired and the summary is rebuilt from the stored batch.",
                "example": "completed"
              },
              "message": {
                "type": "string",
                "example": "The validation has completed."
              },
              "valid_count": {
                "type": "integer",
                "example": 10
              },
              "invalid_count": {
                "type": "integer",
                "example": 2
              },
              "ignored_count": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": 0
              },
              "total_rows": {
                "type": "integer",
                "example": 12
              },
              "download_url": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "URL to download the invalid-rows report. Null when there are no invalid rows.",
                "example": null
              },
              "expires_at": {
                "type": "string",
                "example": "2026-06-08 15:19:10 +0100"
              }
            }
          }
        }
      },
      "V3ValidationProcessingResponse": {
        "type": "object",
        "properties": {
          "validate": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean",
                "example": true
              },
              "status": {
                "type": "string",
                "enum": [
                  "processing"
                ],
                "example": "processing"
              },
              "message": {
                "type": "string",
                "example": "The validation is still processing."
              },
              "valid_count": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Rows validated as valid so far. Null until progress is available.",
                "example": 4
              },
              "invalid_count": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": 1
              },
              "ignored_count": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": 0
              },
              "total_rows": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": 12
              },
              "processed": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Rows processed so far.",
                "example": 5
              },
              "download_url": {
                "type": "null",
                "description": "Always null while processing.",
                "example": null
              },
              "expires_at": {
                "type": "string",
                "format": "date-time",
                "example": "2026-06-08T15:19:10.931Z"
              }
            }
          }
        }
      },
      "V3ValidationFailedResponse": {
        "type": "object",
        "description": "Returned with HTTP 422 when the validation failed (`status` is the failed job status, message \"The validation failed.\") or when the batch has not been validated yet (`status` \"not_validated\", message \"Batch has not been validated yet.\"; only `success`, `status`, `message` and `errors` are present in that case).",
        "properties": {
          "validate": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "status": {
                "type": "string",
                "example": "failed",
                "description": "Failed job status, or `not_validated`."
              },
              "message": {
                "type": "string",
                "example": "The validation failed."
              },
              "errors": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": [
                  "Batch has not been validated yet."
                ]
              },
              "valid_count": {
                "type": "null",
                "example": null
              },
              "invalid_count": {
                "type": "null",
                "example": null
              },
              "total_rows": {
                "type": "null",
                "example": null
              },
              "download_url": {
                "type": "null",
                "example": null
              },
              "expires_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "example": "2026-06-08T15:19:10.931Z"
              }
            }
          }
        }
      },
      "V3ValidationErrorResponse": {
        "type": "object",
        "description": "Returned with HTTP 500 when the validation job appears stuck (`status` \"stuck\", message \"The validation appears to be stuck. Please retry.\") or its status can no longer be found (`status` \"unknown\", message \"Job status not found. The job may have expired or failed.\"). If checking the status itself fails, `status` is absent and `message` is \"Error checking validation status\".",
        "properties": {
          "validate": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "status": {
                "type": "string",
                "enum": [
                  "stuck",
                  "unknown"
                ],
                "example": "stuck"
              },
              "message": {
                "type": "string",
                "example": "The validation appears to be stuck. Please retry."
              }
            }
          }
        }
      },
      "V3CatalogImportProcessingResponse": {
        "type": "object",
        "description": "Returned with HTTP 202 while a product or client import is still running. The counters are present only once progress is known.",
        "properties": {
          "status": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean",
                "example": true
              },
              "status": {
                "type": "string",
                "example": "processing"
              },
              "message": {
                "type": "string",
                "example": "The import is still processing."
              },
              "total_rows": {
                "type": "integer",
                "example": 120
              },
              "processed": {
                "type": "integer",
                "example": 40
              },
              "created_count": {
                "type": "integer",
                "example": 38
              },
              "failed_count": {
                "type": "integer",
                "example": 2
              }
            }
          }
        }
      },
      "V3CatalogImportFailedResponse": {
        "type": "object",
        "description": "Returned with HTTP 422 when a product or client import failed. The counters are present only when known.",
        "properties": {
          "status": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "status": {
                "type": "string",
                "example": "failed"
              },
              "message": {
                "type": "string",
                "example": "The import failed."
              },
              "import": {
                "type": "object",
                "properties": {
                  "batch_metadata_id": {
                    "type": "integer",
                    "example": 123
                  },
                  "created_count": {
                    "type": "integer",
                    "example": 38
                  },
                  "failed_count": {
                    "type": "integer",
                    "example": 2
                  },
                  "failed_download_url": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": null
                  }
                }
              },
              "errors": {
                "type": "array",
                "description": "Error details, when available (may be empty or absent).",
                "items": {
                  "type": "string"
                },
                "example": []
              },
              "total_rows": {
                "type": "integer",
                "example": 40
              },
              "processed": {
                "type": "integer",
                "example": 40
              },
              "created_count": {
                "type": "integer",
                "example": 38
              },
              "failed_count": {
                "type": "integer",
                "example": 2
              }
            }
          }
        }
      },
      "V3BatchInvoiceMetadataResponse": {
        "type": "object",
        "description": "Shared by the invoice, product and client imports. For product and client imports the invoice-only fields (`doc_type`, `doc_status`, `sequence_id`, `sequence`, `exemption_reason_id`, `discount_type`) are always `null` and `send_by_email` is `false`.",
        "properties": {
          "import": {
            "$ref": "#/components/schemas/V3ImportBatchMetadata"
          }
        }
      },
      "V3BatchInvoiceUploadResponse": {
        "type": "object",
        "description": "Shared by the invoice, product and client imports. For product and client imports the invoice-only fields (`doc_type`, `doc_status`, `sequence_id`, `sequence`, `exemption_reason_id`, `discount_type`) are always `null` and `send_by_email` is `false`.",
        "properties": {
          "import": {
            "type": "object",
            "properties": {
              "batch_metadata_id": {
                "type": "integer",
                "example": 0
              },
              "batch_name": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "My import"
              },
              "status": {
                "type": "string",
                "enum": [
                  "started",
                  "mapping",
                  "validating",
                  "validated",
                  "configured",
                  "importing",
                  "sending_email",
                  "completed",
                  "failed"
                ],
                "example": "started"
              },
              "date": {
                "type": "string",
                "format": "date-time",
                "example": "2026-06-08T15:19:10.902Z"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time",
                "example": "2026-06-08T15:19:10.902Z"
              },
              "doc_type": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "invoices"
              },
              "doc_status": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "draft"
              },
              "sequence_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": 12345
              },
              "sequence": {
                "type": [
                  "string",
                  "null"
                ],
                "example": ""
              },
              "send_by_email": {
                "type": "boolean",
                "example": false
              },
              "header": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Stored as a string: the `exclude_first_line` value sent to process, as Rails casts it (JSON `true` → \"t\", `false` → \"f\"). Null until the CSV is processed, and still null after processing when `exclude_first_line` was not sent.",
                "example": null
              },
              "separator": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "filename": {
                "type": "string",
                "example": "import.csv"
              },
              "exemption_reason_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": null
              },
              "discount_type": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              }
            }
          }
        }
      },
      "V3BatchInvoiceProcessResponse": {
        "type": "object",
        "properties": {
          "import": {
            "type": "object",
            "properties": {
              "batch_metadata_id": {
                "type": "integer",
                "example": 0
              },
              "batch_name": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "My import"
              },
              "status": {
                "type": "string",
                "enum": [
                  "started",
                  "mapping",
                  "validating",
                  "validated",
                  "configured",
                  "importing",
                  "sending_email",
                  "completed",
                  "failed"
                ],
                "example": "mapping"
              },
              "date": {
                "type": "string",
                "format": "date-time",
                "example": "2026-06-08T15:19:10.908Z"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time",
                "example": "2026-06-08T15:19:10.908Z"
              },
              "doc_type": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "doc_status": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "sequence_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": null
              },
              "sequence": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "send_by_email": {
                "type": "boolean",
                "example": false
              },
              "header": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Stored as a string: the `exclude_first_line` value sent to process, as Rails casts it (JSON `true` → \"t\", `false` → \"f\"). Null until the CSV is processed, and still null after processing when `exclude_first_line` was not sent.",
                "example": "t"
              },
              "separator": {
                "type": "string",
                "example": ","
              },
              "filename": {
                "type": "string",
                "example": "import.csv"
              },
              "exemption_reason_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": null
              },
              "discount_type": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "mapping": {
                "type": "object",
                "properties": {
                  "client": {
                    "type": "object",
                    "additionalProperties": {
                      "$ref": "#/components/schemas/V3MappingFieldEntry"
                    }
                  },
                  "document": {
                    "type": "object",
                    "additionalProperties": {
                      "$ref": "#/components/schemas/V3MappingFieldEntry"
                    }
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": {
                        "$ref": "#/components/schemas/V3MappingFieldEntry"
                      }
                    }
                  },
                  "cells": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/V3CellEntry"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "V3InvoiceMappingResponse": {
        "type": "object",
        "properties": {
          "mapping": {
            "type": "object",
            "properties": {
              "client": {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/V3MappingFieldEntry"
                }
              },
              "document": {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/V3MappingFieldEntry"
                }
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": {
                    "$ref": "#/components/schemas/V3MappingFieldEntry"
                  }
                }
              },
              "cells": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/V3CellEntry"
                }
              }
            }
          }
        }
      },
      "V3InvoiceMappingRequest": {
        "type": "object",
        "properties": {
          "mapping": {
            "type": "object",
            "properties": {
              "client": {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/V3MappingFieldEntry"
                }
              },
              "document": {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/V3MappingFieldEntry"
                }
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": {
                    "$ref": "#/components/schemas/V3MappingFieldEntry"
                  }
                }
              }
            }
          }
        }
      },
      "V3BatchInvoiceConfigureOptions": {
        "type": "object",
        "properties": {
          "sequences": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 1
                },
                "serie": {
                  "type": "string",
                  "example": "A"
                },
                "category": {
                  "type": "string",
                  "example": "invoices"
                }
              }
            }
          },
          "exemption_reasons": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 1
                },
                "code": {
                  "type": "string",
                  "example": "M00"
                },
                "reason": {
                  "type": "string",
                  "example": "Isento"
                }
              }
            }
          }
        }
      },
      "V3BatchInvoiceConfigureRequest": {
        "type": "object",
        "required": [
          "configure"
        ],
        "properties": {
          "configure": {
            "type": "object",
            "required": [
              "name"
            ],
            "properties": {
              "name": {
                "type": "string",
                "maxLength": 255,
                "description": "Required (leading/trailing spaces are stripped). Must not be used by another document batch of the account (\"Name is already used by another import batch\"; blank → \"Name can't be blank\").",
                "example": "My import batch"
              },
              "doc_type": {
                "type": "string",
                "enum": [
                  "invoices",
                  "invoice_receipts"
                ],
                "example": "invoices"
              },
              "doc_status": {
                "type": "string",
                "enum": [
                  "draft",
                  "final"
                ],
                "example": "draft"
              },
              "sequence_id": {
                "type": "integer",
                "description": "Must be a sequence of the account (\"must belong to the current account\"), of the same category as `doc_type` (\"must match the selected document type\") and registered at the tax authority (\"must be a registered sequence\"). See configure_options for the valid sequences.",
                "example": 12345
              },
              "send_by_email": {
                "type": "boolean",
                "example": false
              },
              "exemption_reason_id": {
                "type": "integer",
                "description": "Must be an existing exemption reason (\"must be a valid exemption reason that exists\").",
                "example": 1
              },
              "discount_type": {
                "type": "string",
                "enum": [
                  "percentage",
                  "absolute"
                ],
                "example": "percentage"
              }
            }
          }
        }
      },
      "V3BatchInvoiceConfigureResponse": {
        "type": "object",
        "properties": {
          "configure": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "example": 123
              },
              "account_id": {
                "type": "integer",
                "example": 0
              },
              "user_id": {
                "type": "integer",
                "example": 0
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "My import batch"
              },
              "status": {
                "type": "string",
                "enum": [
                  "started",
                  "mapping",
                  "validating",
                  "validated",
                  "configured",
                  "importing",
                  "sending_email",
                  "completed",
                  "failed"
                ],
                "example": "configured"
              },
              "doc_type": {
                "type": "string",
                "example": "invoices"
              },
              "doc_status": {
                "type": "string",
                "example": "draft"
              },
              "filename": {
                "type": "string",
                "example": "import.csv"
              },
              "import_type": {
                "type": "string",
                "example": "invoices"
              },
              "separator": {
                "type": "string",
                "example": ","
              },
              "header": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Stored as a string: the `exclude_first_line` value sent to process, as Rails casts it (JSON `true` → \"t\", `false` → \"f\"). Null until the CSV is processed, and still null after processing when `exclude_first_line` was not sent.",
                "example": "t"
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "example": "2026-06-08T15:19:10.908Z"
              },
              "updated_at": {
                "type": "string",
                "format": "date-time",
                "example": "2026-06-08T15:19:10.908Z"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time",
                "example": "2026-06-08T15:19:10.908Z"
              },
              "sequence_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": 12345
              },
              "send_by_email": {
                "type": "boolean",
                "example": false
              },
              "exemption_reason_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": 0
              },
              "discount_type": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "percentage"
              }
            }
          }
        }
      },
      "V3AvailableDocsResponse": {
        "type": "object",
        "properties": {
          "available_docs": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean",
                "example": true
              },
              "can_import": {
                "type": "boolean",
                "example": true
              },
              "required_count": {
                "type": "integer",
                "example": 15
              },
              "remaining_documents": {
                "type": "integer",
                "example": 100
              }
            }
          }
        }
      },
      "V3BatchStatusCompletedResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean",
                "example": true
              },
              "status": {
                "type": "string",
                "enum": [
                  "completed"
                ],
                "example": "completed"
              },
              "message": {
                "type": "string",
                "example": "The import has completed."
              },
              "total_rows": {
                "type": "integer",
                "example": 0
              },
              "processed": {
                "type": "integer",
                "example": 0
              },
              "created_count": {
                "type": "integer",
                "example": 0
              },
              "failed_count": {
                "type": "integer",
                "example": 0
              },
              "import": {
                "type": "object",
                "properties": {
                  "batch_metadata_id": {
                    "type": "integer",
                    "example": 0
                  },
                  "created_count": {
                    "type": "integer",
                    "example": 0
                  },
                  "document_batch_id": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "example": 0
                  },
                  "failed_count": {
                    "type": "integer",
                    "example": 0
                  },
                  "failed_download_url": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "URL of the CSV with the rows that were not created. Null when every row was created.",
                    "example": null
                  }
                }
              }
            }
          }
        }
      },
      "V3BatchStatusProcessingResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean",
                "example": true
              },
              "status": {
                "type": "string",
                "enum": [
                  "processing",
                  "sending_email"
                ],
                "description": "`sending_email`: documents were created and are being sent by email (message \"Documents were created successfully. Sending by email.\").",
                "example": "processing"
              },
              "message": {
                "type": "string",
                "example": "The import is still processing."
              },
              "total_rows": {
                "type": "integer",
                "example": 0
              },
              "processed": {
                "type": "integer",
                "example": 0
              },
              "created_count": {
                "type": "integer",
                "example": 0
              },
              "failed_count": {
                "type": "integer",
                "example": 0
              },
              "import": {
                "type": "object"
              }
            }
          }
        }
      },
      "V3BatchStatusFailedResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "status": {
                "type": "string",
                "enum": [
                  "failed",
                  "exception_occurred",
                  "interrupted"
                ],
                "description": "`interrupted`: a previous import was interrupted (message \"The previous import was interrupted. Start a new import to retry.\"); start a new import to retry.",
                "example": "failed"
              },
              "message": {
                "type": "string",
                "example": "The import failed."
              },
              "total_rows": {
                "type": "integer",
                "example": 0
              },
              "processed": {
                "type": "integer",
                "example": 0
              },
              "created_count": {
                "type": "integer",
                "example": 0
              },
              "failed_count": {
                "type": "integer",
                "example": 0
              },
              "import": {
                "type": "object"
              },
              "errors": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "V3BatchStatusUnknownResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean",
                "example": false
              },
              "status": {
                "type": "string",
                "enum": [
                  "stuck",
                  "unknown"
                ],
                "description": "`stuck`: message \"The import appears to be stuck. Please retry.\". Absent (message \"Error checking status\") when the status check itself fails.",
                "example": "unknown"
              },
              "message": {
                "type": "string",
                "description": "May simply be \"Job status not found. The job may have expired or failed.\" when there is no import job to report on.",
                "example": "Job status not found. The job may have expired or failed."
              },
              "total_rows": {
                "type": "integer",
                "example": 0
              },
              "processed": {
                "type": "integer",
                "example": 0
              },
              "created_count": {
                "type": "integer",
                "example": 0
              },
              "failed_count": {
                "type": "integer",
                "example": 0
              }
            }
          }
        }
      },
      "V3BatchProductProcessResponse": {
        "type": "object",
        "properties": {
          "import": {
            "type": "object",
            "properties": {
              "batch_metadata_id": {
                "type": "integer",
                "example": 0
              },
              "batch_name": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "My product import"
              },
              "status": {
                "type": "string",
                "enum": [
                  "started",
                  "mapping",
                  "validating",
                  "validated",
                  "configured",
                  "importing",
                  "sending_email",
                  "completed",
                  "failed"
                ],
                "example": "mapping"
              },
              "date": {
                "type": "string",
                "format": "date-time",
                "example": "2026-06-08T15:19:10.940Z"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time",
                "example": "2026-06-08T15:19:10.940Z"
              },
              "doc_type": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "doc_status": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "sequence_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": null
              },
              "sequence": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "send_by_email": {
                "type": "boolean",
                "example": false
              },
              "header": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Stored as a string: the `exclude_first_line` value sent to process, as Rails casts it (JSON `true` → \"t\", `false` → \"f\"). Null until the CSV is processed, and still null after processing when `exclude_first_line` was not sent.",
                "example": "t"
              },
              "separator": {
                "type": "string",
                "example": ","
              },
              "filename": {
                "type": "string",
                "example": "import.csv"
              },
              "exemption_reason_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": null
              },
              "discount_type": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "mapping": {
                "type": "object",
                "properties": {
                  "product": {
                    "type": "object",
                    "additionalProperties": {
                      "$ref": "#/components/schemas/V3MappingFieldEntry"
                    }
                  },
                  "cells": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/V3CellEntry"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "V3ProductMappingResponse": {
        "type": "object",
        "properties": {
          "mapping": {
            "type": "object",
            "properties": {
              "product": {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/V3MappingFieldEntry"
                }
              },
              "cells": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/V3CellEntry"
                }
              }
            }
          }
        }
      },
      "V3ProductMappingRequest": {
        "type": "object",
        "properties": {
          "mapping": {
            "type": "object",
            "description": "Only `product` is read. The stored `cells` are always kept; a `cells` key sent here is ignored.",
            "properties": {
              "product": {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/V3MappingFieldEntry"
                }
              }
            }
          }
        }
      },
      "V3ProductBatchStatusCompletedResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean",
                "example": true
              },
              "status": {
                "type": "string",
                "example": "completed"
              },
              "message": {
                "type": "string",
                "example": "The import has completed."
              },
              "total_rows": {
                "type": "integer",
                "example": 1
              },
              "processed": {
                "type": "integer",
                "example": 1
              },
              "created_count": {
                "type": "integer",
                "example": 1
              },
              "failed_count": {
                "type": "integer",
                "example": 0
              },
              "import": {
                "type": "object",
                "properties": {
                  "batch_metadata_id": {
                    "type": "integer",
                    "example": 0
                  },
                  "created_count": {
                    "type": "integer",
                    "example": 0
                  },
                  "failed_count": {
                    "type": "integer",
                    "example": 0
                  },
                  "failed_download_url": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": null
                  }
                }
              }
            }
          }
        }
      },
      "V3BatchClientProcessResponse": {
        "type": "object",
        "properties": {
          "import": {
            "type": "object",
            "properties": {
              "batch_metadata_id": {
                "type": "integer",
                "example": 0
              },
              "batch_name": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "My client import"
              },
              "status": {
                "type": "string",
                "enum": [
                  "started",
                  "mapping",
                  "validating",
                  "validated",
                  "configured",
                  "importing",
                  "sending_email",
                  "completed",
                  "failed"
                ],
                "example": "mapping"
              },
              "date": {
                "type": "string",
                "format": "date-time",
                "example": "2026-06-08T15:19:10.953Z"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time",
                "example": "2026-06-08T15:19:10.953Z"
              },
              "doc_type": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "doc_status": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "sequence_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": null
              },
              "sequence": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "send_by_email": {
                "type": "boolean",
                "example": false
              },
              "header": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Stored as a string: the `exclude_first_line` value sent to process, as Rails casts it (JSON `true` → \"t\", `false` → \"f\"). Null until the CSV is processed, and still null after processing when `exclude_first_line` was not sent.",
                "example": "t"
              },
              "separator": {
                "type": "string",
                "example": ","
              },
              "filename": {
                "type": "string",
                "example": "import.csv"
              },
              "exemption_reason_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": null
              },
              "discount_type": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "mapping": {
                "type": "object",
                "properties": {
                  "client": {
                    "type": "object",
                    "additionalProperties": {
                      "$ref": "#/components/schemas/V3MappingFieldEntry"
                    }
                  },
                  "cells": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/V3CellEntry"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "V3ClientMappingResponse": {
        "type": "object",
        "properties": {
          "mapping": {
            "type": "object",
            "properties": {
              "client": {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/V3MappingFieldEntry"
                }
              },
              "cells": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/V3CellEntry"
                }
              }
            }
          }
        }
      },
      "V3ClientMappingRequest": {
        "type": "object",
        "properties": {
          "mapping": {
            "type": "object",
            "description": "Only `client` is read. The stored `cells` are always kept; a `cells` key sent here is ignored.",
            "properties": {
              "client": {
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/V3MappingFieldEntry"
                }
              }
            }
          }
        }
      },
      "V3ItemListResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3ItemObject"
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "total_entries": {
                "type": "integer",
                "example": 1
              },
              "current_page": {
                "type": "integer",
                "example": 1
              },
              "total_pages": {
                "type": "integer",
                "example": 1
              },
              "per_page": {
                "type": "integer",
                "example": 10
              }
            }
          }
        }
      },
      "V3ItemResponse": {
        "type": "object",
        "properties": {
          "item": {
            "$ref": "#/components/schemas/V3ItemObject"
          }
        }
      },
      "V3ItemDetailResponse": {
        "type": "object",
        "properties": {
          "item": {
            "$ref": "#/components/schemas/V3ItemDetailObject"
          }
        }
      },
      "V3CreateItemRequest": {
        "type": "object",
        "required": [
          "item"
        ],
        "properties": {
          "item": {
            "allOf": [
              {
                "$ref": "#/components/schemas/V3ItemWritableFields"
              },
              {
                "type": "object",
                "required": [
                  "code",
                  "unit_price"
                ]
              }
            ]
          }
        }
      },
      "V3UpdateItemRequest": {
        "type": "object",
        "required": [
          "item"
        ],
        "description": "Partial update. No field inside `item` is required. Note that an omitted `retention` is reset to `0`.",
        "properties": {
          "item": {
            "$ref": "#/components/schemas/V3ItemWritableFields"
          }
        }
      },
      "V3ScheduleListResponse": {
        "type": "object",
        "properties": {
          "schedules": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3ScheduleListItem"
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "total_entries": {
                "type": "integer",
                "example": 1
              },
              "current_page": {
                "type": "integer",
                "example": 1
              },
              "total_pages": {
                "type": "integer",
                "example": 1
              },
              "per_page": {
                "type": "integer",
                "example": 10
              }
            }
          }
        }
      },
      "V3ScheduleResponse": {
        "type": "object",
        "properties": {
          "schedule": {
            "$ref": "#/components/schemas/V3ScheduleObject"
          }
        }
      },
      "V3CreateScheduleRequest": {
        "type": "object",
        "required": [
          "schedule"
        ],
        "properties": {
          "schedule": {
            "type": "object",
            "required": [
              "document_type",
              "description",
              "interval",
              "type"
            ],
            "properties": {
              "document_type": {
                "type": "string",
                "enum": [
                  "invoice",
                  "invoice_receipt",
                  "simplified_invoice",
                  "Invoice",
                  "InvoiceReceipt",
                  "SimplifiedInvoice"
                ],
                "description": "Document type to generate. Accepts the key (`invoice`) or the stored value (`Invoice`); responses always return the key.",
                "example": "invoice"
              },
              "interval": {
                "type": "integer",
                "minimum": 1,
                "description": "Must be greater than 0.",
                "example": 1
              },
              "type": {
                "type": "string",
                "enum": [
                  "Daily",
                  "Monthly",
                  "Yearly"
                ],
                "example": "Monthly"
              },
              "description": {
                "type": "string",
                "example": "Monthly invoice",
                "maxLength": 255
              },
              "start_date": {
                "type": "string",
                "format": "date",
                "example": "2030-01-01",
                "description": "On create it must be tomorrow or later; today or a past date is rejected with 422 (\"Start date cannot be today, must be tomorrow or later\"). Defaults to tomorrow when omitted."
              },
              "end_date": {
                "type": "string",
                "format": "date",
                "example": "2035-01-01"
              },
              "to_create_back_invoices": {
                "type": "boolean",
                "example": false,
                "description": "Accepted, but has no effect when creating a schedule: back invoices are only generated for dates between `start_date` and today, and on create `start_date` must be tomorrow or later."
              },
              "to_send": {
                "type": "boolean",
                "example": true
              },
              "email_cc": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "maxLength": 255
              },
              "email_bcc": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "maxLength": 255
              },
              "template": {
                "$ref": "#/components/schemas/V3ScheduleTemplate"
              }
            }
          }
        }
      },
      "V3ScheduleTimelineResponse": {
        "type": "object",
        "properties": {
          "timeline": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3ScheduleTimelineItem"
            }
          }
        }
      },
      "V3TaxListResponse": {
        "type": "object",
        "properties": {
          "taxes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3TaxObject"
            }
          }
        }
      },
      "V3TaxResponse": {
        "type": "object",
        "properties": {
          "tax": {
            "$ref": "#/components/schemas/V3TaxObject"
          }
        }
      },
      "V3CreateTaxRequest": {
        "type": "object",
        "required": [
          "tax"
        ],
        "description": "An empty body (no `tax` root and no top-level tax field) fails with HTTP 500\n(`Something went terribly wrong.`); top-level fields are wrapped into `tax` automatically.\n`region` is required unless `name` is `Isento`.",
        "properties": {
          "tax": {
            "allOf": [
              {
                "$ref": "#/components/schemas/V3TaxWritableFields"
              },
              {
                "type": "object",
                "required": [
                  "name",
                  "value"
                ]
              }
            ]
          }
        }
      },
      "V3UpdateTaxRequest": {
        "type": "object",
        "required": [
          "tax"
        ],
        "description": "An empty body (no `tax` root and no top-level tax field) fails with HTTP 500\n(`Something went terribly wrong.`); top-level fields are wrapped into `tax` automatically.\n`default_tax: 1` is applied before the other fields are validated, so it takes effect even\nwhen the update answers 422.",
        "properties": {
          "tax": {
            "$ref": "#/components/schemas/V3TaxWritableFields"
          }
        }
      },
      "V3UserResponse": {
        "type": "object",
        "properties": {
          "user": {
            "$ref": "#/components/schemas/V3UserObject"
          }
        }
      },
      "V3UpdateUserRequest": {
        "type": "object",
        "required": [
          "user"
        ],
        "properties": {
          "user": {
            "type": "object",
            "description": "Required. An empty body (no `user` root and no top-level user field)\nreturns 500; top-level user fields (e.g. `first_name`, `phone`) are\nwrapped into `user` automatically.\n\nTo change the password, send `actual_password` (current password),\n`password` and `password_confirmation`.\n",
            "properties": {
              "name": {
                "type": "string",
                "example": "Jean Dias",
                "description": "Saved as `first_name` (it overrides `first_name` when both are sent). No enforced character limit (text column)."
              },
              "first_name": {
                "type": "string",
                "example": "Jean",
                "description": "Same field as `name`."
              },
              "phone_country_id": {
                "type": "integer",
                "example": 1,
                "description": "Id of the phone calling code (see Phone Calling Codes)."
              },
              "email": {
                "type": "string",
                "example": "john.doe@invoicexpress.com",
                "maxLength": 255,
                "description": "Cannot be changed through this endpoint. Optional; if sent it must equal the user's current email (case-insensitive), otherwise the whole request is rejected with 422 \"Email changes must be requested through POST /users/:id/email_change.\" The same applies to `login`. To change the email use `POST /api/v3/users/{id}/email_change`."
              },
              "phone": {
                "type": "string",
                "example": "987654321",
                "description": "No enforced character limit (text column)."
              },
              "accepted_marketing": {
                "type": "boolean",
                "example": true
              },
              "actual_password": {
                "type": "string",
                "example": "123456",
                "description": "Current password. Required to change the password (see above)."
              },
              "password": {
                "type": "string",
                "example": "yoDWznBeH5j$JP98",
                "minLength": 12,
                "maxLength": 40
              },
              "password_confirmation": {
                "type": "string",
                "example": "yoDWznBeH5j$JP98",
                "minLength": 12,
                "maxLength": 40
              }
            }
          }
        }
      },
      "V3ApiKeyResponse": {
        "type": "object",
        "properties": {
          "account_name": {
            "type": "string",
            "example": "companyname"
          },
          "api_key": {
            "type": "string",
            "example": "aa8e739bbcbb406c90eccbe0825e87c5c1c4c5a9"
          }
        }
      },
      "V3UserAccountsResponse": {
        "type": "object",
        "properties": {
          "accounts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3UserAccountObject"
            }
          }
        }
      },
      "V3RecoverPasswordRequest": {
        "type": "object",
        "required": [
          "user"
        ],
        "properties": {
          "language": {
            "type": "string",
            "enum": [
              "pt",
              "en",
              "es"
            ],
            "example": "en",
            "description": "Optional. Language of the response messages. It can also be sent as a query parameter. Without it (or with another value) the messages use Portuguese (`pt`)."
          },
          "user": {
            "type": "object",
            "required": [
              "email"
            ],
            "properties": {
              "email": {
                "type": "string",
                "example": "john.doe@invoicexpress.com",
                "maxLength": 255,
                "description": "Missing or blank returns 422 \"Enter your email address.\""
              }
            }
          }
        }
      },
      "V3RecoverPasswordResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "We've sent a link to reset your password to your email address."
          }
        }
      },
      "V3ResetPasswordRequest": {
        "type": "object",
        "required": [
          "user"
        ],
        "properties": {
          "language": {
            "type": "string",
            "enum": [
              "pt",
              "en",
              "es"
            ],
            "example": "en",
            "description": "Optional. Language of the response messages. It can also be sent as a query parameter. Without it (or with another value) the messages use the language of the user's account, or Portuguese (`pt`) when the reset code is invalid."
          },
          "user": {
            "type": "object",
            "required": [
              "reset_code",
              "password",
              "password_confirmation"
            ],
            "properties": {
              "reset_code": {
                "type": "string",
                "example": "e72bfdaeb6d719ec975162f8dbbc6733297b0cb0d3d780f4c42163acfb5aa0502285dccacae0cab41d044c19ed21bd9c7c04b3c7eb8e58b16245e0a97e468dfe"
              },
              "password": {
                "type": "string",
                "example": "yoDWznBeH5j$JP98",
                "minLength": 12,
                "maxLength": 40,
                "description": "New password. Must differ from the current one (`Password can't be identical to the current one`)."
              },
              "password_confirmation": {
                "type": "string",
                "example": "yoDWznBeH5j$JP98",
                "minLength": 12,
                "maxLength": 40,
                "description": "Must equal `password` (`Password mismatch`)."
              }
            }
          }
        }
      },
      "V3ResetPasswordResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Password successfully reset."
          }
        }
      },
      "V3CurrencyListResponse": {
        "type": "object",
        "properties": {
          "currencies": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3CurrencyObject"
            }
          }
        }
      },
      "V3CurrencyExchangeRateResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "rate",
          "provider"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Indicates if the exchange rate was successfully fetched",
            "example": true
          },
          "code": {
            "type": "object",
            "required": [
              "from",
              "to"
            ],
            "properties": {
              "from": {
                "type": "string",
                "description": "Source currency code (ISO 4217)",
                "example": "EUR"
              },
              "to": {
                "type": "string",
                "description": "Target currency code (ISO 4217)",
                "example": "USD"
              }
            }
          },
          "rate": {
            "type": "number",
            "description": "Exchange rate from source to target currency",
            "example": 1.1395
          },
          "provider": {
            "type": "object",
            "required": [
              "name",
              "src"
            ],
            "properties": {
              "name": {
                "type": "string",
                "description": "Name of the exchange rate provider",
                "example": "Open Exchange Rates"
              },
              "src": {
                "type": "string",
                "description": "Provider website URL",
                "example": "https://openexchangerates.org/"
              }
            }
          }
        }
      },
      "V3CurrencyExchangeRateFailureResponse": {
        "type": "object",
        "description": "Returned with HTTP 200 when no rate could be found — for example an unknown currency code, or a code not in upper case (codes are case-sensitive, so `eur` is not found).",
        "required": [
          "success"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ],
            "example": false
          }
        }
      },
      "V3DashboardActiveClientsResponse": {
        "type": "object",
        "properties": {
          "months": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "year": {
                  "type": "integer",
                  "example": 2026
                },
                "month": {
                  "type": "integer",
                  "example": 5
                },
                "recurring_clients": {
                  "type": "integer",
                  "example": 11900
                },
                "new_clients": {
                  "type": "integer",
                  "example": 5100
                }
              }
            }
          }
        }
      },
      "V3DashboardClientsKpiResponse": {
        "type": "object",
        "properties": {
          "total_active_clients": {
            "type": "integer",
            "description": "Sum of recurring and new clients for the last 12 months",
            "example": 1200
          },
          "total_active_clients_change_percent": {
            "type": "number",
            "description": "Percentage change compared to the homologous 12-month period",
            "example": 15.5
          },
          "new_clients_in_period": {
            "type": "integer",
            "description": "Sum of new clients for the last 12 months",
            "example": 300
          },
          "avg_revenue_per_active_client": {
            "type": "number",
            "description": "Average revenue per active client based on total_before_taxes from report_client_invoicings",
            "example": 450.75
          },
          "avg_revenue_per_new_client": {
            "type": "number",
            "description": "Average revenue per new client based on total_before_taxes from invoicing_per_clients filtered by first_invoice",
            "example": 320
          }
        }
      },
      "V3DashboardClientsDependencyResponse": {
        "type": "object",
        "properties": {
          "segments": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "client_id": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "Null when this segment aggregates the remaining smaller clients (client_name \"others\")",
                  "example": 1
                },
                "invoicing": {
                  "type": "number",
                  "example": 2647.25
                },
                "client_name": {
                  "type": "string",
                  "example": "Rauva"
                },
                "share_percent": {
                  "type": "number",
                  "example": 35.89
                }
              }
            }
          }
        }
      },
      "V3DashboardDailyInvoicingResponse": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "date": {
              "type": "string",
              "example": "2025-11-04"
            },
            "value": {
              "type": "number",
              "example": 100
            },
            "vat": {
              "type": "number",
              "example": 23
            }
          }
        }
      },
      "V3CreateFavoriteRequest": {
        "type": "object",
        "required": [
          "tab",
          "favorite"
        ],
        "description": "A missing `tab` → 422 (\"param is missing or the value is empty or invalid: tab\"). A missing `favorite` key never gives 422: the top-level body is wrapped into `favorite` automatically.",
        "properties": {
          "tab": {
            "type": "string",
            "example": "Invoices"
          },
          "favorite": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "example": "fav1"
              },
              "filters": {
                "$ref": "#/components/schemas/V3FavoriteFilters"
              }
            }
          }
        }
      },
      "V3FavoriteCreateResponse": {
        "type": "object",
        "properties": {
          "favorite": {
            "type": "object",
            "properties": {
              "uid": {
                "type": "string",
                "example": "bddeb153-0e80-4238-846f-546c0327f451"
              }
            }
          }
        }
      },
      "V3FavoriteDetailResponse": {
        "type": "object",
        "properties": {
          "filters": {
            "$ref": "#/components/schemas/V3FavoriteFilters"
          }
        }
      },
      "V3UpdateFavoriteRequest": {
        "type": "object",
        "required": [
          "tab",
          "favorite"
        ],
        "description": "A missing `tab` → 422 (\"param is missing or the value is empty or invalid: tab\"). A missing `favorite` key never gives 422: the top-level body is wrapped into `favorite` automatically. Only the fields sent inside `favorite` change.",
        "properties": {
          "tab": {
            "type": "string",
            "example": "Invoices"
          },
          "favorite": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "New name. Kept when absent or blank.",
                "example": "new favorite"
              },
              "filters": {
                "description": "When present (not blank), replaces the stored filters entirely.",
                "allOf": [
                  {
                    "$ref": "#/components/schemas/V3FavoriteFilters"
                  }
                ]
              }
            }
          }
        }
      },
      "V3FavoriteUpdateResponse": {
        "type": "object",
        "properties": {
          "favorite": {
            "type": "object",
            "properties": {
              "filters": {
                "$ref": "#/components/schemas/V3FavoriteFilters"
              },
              "name": {
                "type": "string",
                "example": "new favorite"
              },
              "uid": {
                "type": "string",
                "example": "72b0b781-f7f3-40fb-ae44-3762611fc0a8"
              },
              "AccountID_UserID_Tab": {
                "type": "string",
                "description": "Internal composite key: account ID, user ID, and tab, joined by ::",
                "example": "148306::147436::Invoices"
              }
            }
          }
        }
      },
      "V3FavoriteListResponse": {
        "type": "object",
        "properties": {
          "favorites": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3FavoriteSummaryObject"
            }
          }
        }
      },
      "V3PaymentServiceListResponse": {
        "type": "object",
        "properties": {
          "payment_services": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3PaymentServiceObject"
            }
          }
        }
      },
      "V3PaymentServiceResponse": {
        "type": "object",
        "properties": {
          "payment_service": {
            "$ref": "#/components/schemas/V3PaymentServiceObject"
          }
        }
      },
      "V3CreatePaymentServiceRequest": {
        "type": "object",
        "required": [
          "id",
          "payment_service"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "description": "Id of the payment service to register (top level). Missing → 400; unknown id → 500.",
            "example": 1
          },
          "payment_service": {
            "type": "object",
            "description": "Required. Missing → 500 (generic error).",
            "properties": {
              "is_partner": {
                "type": "boolean",
                "description": "Easypay only. `true` registers a new Easypay partner account from the company data sent in `credentials` (company_responsible, company_name, address, postal_code, city, country, phone, email, invoice_email, tecnical_email, notification_email, iban, vat_number); otherwise the existing Easypay credentials (ep_user, ep_cin, entity, public_key, s_code) are used.",
                "example": false
              },
              "credentials": {
                "type": "object",
                "description": "Credential fields required by the selected provider, as key/value pairs.",
                "properties": {
                  "key": {
                    "type": "string",
                    "example": "value"
                  }
                }
              },
              "extra_options": {
                "$ref": "#/components/schemas/V3PaymentServiceExtraOptions"
              }
            }
          }
        }
      },
      "V3UpdatePaymentServiceRequest": {
        "type": "object",
        "required": [
          "payment_service"
        ],
        "properties": {
          "payment_service": {
            "type": "object",
            "description": "Required. Missing → 400 (when `id` is the configured service).",
            "properties": {
              "credentials": {
                "type": "object",
                "description": "Credential fields required by the selected provider, as key/value pairs. A credential the provider marks as not editable must be sent unchanged (or omitted); a different value → 422 (\"This field cannot be edited.\").",
                "properties": {
                  "key": {
                    "type": "string",
                    "example": "value"
                  }
                }
              },
              "extra_options": {
                "$ref": "#/components/schemas/V3PaymentServiceExtraOptions"
              }
            }
          }
        }
      },
      "V3PaymentServiceReferencesResponse": {
        "type": "object",
        "properties": {
          "references": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3PaymentServiceReferenceObject"
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "total_entries": {
                "type": "integer",
                "example": 142
              },
              "current_page": {
                "type": "integer",
                "example": 1
              },
              "total_pages": {
                "type": "integer",
                "example": 15
              },
              "per_page": {
                "type": "integer",
                "example": 10
              }
            }
          }
        }
      },
      "V3PhoneCallingCodeListResponse": {
        "type": "object",
        "properties": {
          "phone_calling_codes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3PhoneCallingCodeObject"
            }
          }
        }
      },
      "V3BalancePerClientResponse": {
        "type": "object",
        "properties": {
          "balance_per_client": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3BalancePerClientObject"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/V3ReportsPagination"
          },
          "page_total": {
            "$ref": "#/components/schemas/V3BalancePerClientTotals"
          }
        }
      },
      "V3BalancePerClientExportResponse": {
        "type": "object",
        "required": [
          "url",
          "filename"
        ],
        "properties": {
          "url": {
            "type": "string",
            "description": "Presigned URL to download the XLSX file. Valid for about 7 days (597600 seconds, `X-Amz-Expires=597600`).",
            "example": "https://invoicexpress-downloads.s3.eu-west-1.amazonaws.com/..."
          },
          "filename": {
            "type": "string",
            "description": "Suggested filename for the download",
            "example": "balance_per_client_2025-02-23.xlsx"
          }
        }
      },
      "V3BalancePerClientSummaryResponse": {
        "type": "object",
        "properties": {
          "summary": {
            "$ref": "#/components/schemas/V3BalancePerClientSummaryObject"
          }
        }
      },
      "V3SaftExportResponse": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Link to download your SAF-T file. Absent when there are no documents to export in the selected period — see message instead.",
            "example": "https://some.url"
          },
          "message": {
            "type": "string",
            "description": "Present instead of url when there are no documents to export in the selected period.",
            "example": "There aren't any documents to export on the selected period."
          }
        }
      },
      "V3SaftExportPendingResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "The SAF-T file generation was started. Please keep requesting until you get back the url."
          }
        }
      },
      "V3SaftExportConflictResponse": {
        "type": "object",
        "description": "Returned when the company information required for the SAF-T is incomplete. Fill in the missing company data and try again.",
        "properties": {
          "message": {
            "type": "string",
            "example": "Warning! There is required information missing from Company information. Before you export the SAF-T PT, please go to Company information and fill out the missing fields."
          }
        }
      },
      "V3TaxCountryListResponse": {
        "type": "object",
        "properties": {
          "tax_countries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3TaxCountryObject"
            }
          }
        }
      },
      "V3DigitalSignatureProviderListResponse": {
        "type": "object",
        "properties": {
          "providers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3DigitalSignatureProviderObject"
            }
          }
        }
      },
      "V3DigitalSignatureAccountProviderObject": {
        "type": "object",
        "description": "The account's provider link. Credentials are not part of this object (see the credentials endpoints).",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "consent_agreement": {
            "type": "boolean",
            "example": true
          },
          "provider": {
            "type": [
              "object",
              "null"
            ],
            "description": "The linked provider. Same fields as the providers list except `in_use`, which is not returned here.",
            "properties": {
              "id": {
                "type": "integer",
                "example": 1
              },
              "name": {
                "type": "string",
                "example": "Multicert"
              },
              "identifier": {
                "type": "string",
                "example": "multicert"
              },
              "description": {
                "type": "string",
                "description": "Localized text in the account language. May contain HTML (e.g. an `<a href>` link for Multicert); render or strip it accordingly. Empty string when there is no text for the provider.",
                "example": "Digitally sign your documents using the Electronic Invoice Signing Service (SAFE)."
              },
              "grant_type": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "client_credentials"
              },
              "url_image": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "/digital_signatures/providers/multicert-logo.png"
              },
              "url_guide": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "https://invoicexpress.helpscoutdocs.com/article/347-assinatura-digital-guia-passo-a-passo-para-a-ativacao"
              },
              "url_auth": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              },
              "expired": {
                "type": [
                  "boolean",
                  "null"
                ],
                "example": false
              },
              "expiration_date": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null
              }
            }
          }
        }
      },
      "V3CreateDigitalSignatureAccountProviderRequest": {
        "type": "object",
        "required": [
          "provider_id",
          "client_id",
          "client_secret",
          "consent_agreement"
        ],
        "description": "Parameters are sent at the top level (no wrapper). The `client_id` / `client_secret` pair is checked with the provider before anything is saved.",
        "properties": {
          "provider_id": {
            "type": "integer",
            "description": "Id of a provider (see the providers list). Missing or unknown → 404.",
            "example": 1
          },
          "client_id": {
            "type": "string",
            "example": "3b897ad6-cce4-4c54-a7e7-2bd00b83ab85"
          },
          "client_secret": {
            "type": "string",
            "example": "ChvH5AUVhLNU"
          },
          "consent_agreement": {
            "type": "boolean",
            "enum": [
              true
            ],
            "description": "Must be `true`; `false` or missing → 422 (`consent_agreement: [\"can't be blank\"]`).",
            "example": true
          }
        }
      },
      "V3DigitalSignatureCredentialsObject": {
        "type": "object",
        "required": [
          "client_id",
          "client_secret"
        ],
        "properties": {
          "client_id": {
            "type": "string",
            "example": "3b897ad6-cce4-4c54-a7e7-2bd00b83ab85"
          },
          "client_secret": {
            "type": "string",
            "example": "ChvH5AUVhLNU"
          }
        }
      },
      "V3DigitalSignatureInfoResponse": {
        "type": "object",
        "properties": {
          "digital_signature_item": {
            "description": "The account's digital signature configuration, or \"NOT_CONFIGURED\" if no digital signature has been set up.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/V3DigitalSignatureInfoObject"
              },
              {
                "type": "string",
                "example": "NOT_CONFIGURED"
              }
            ]
          }
        }
      },
      "V3DigitalSignatureDocumentStatusResponse": {
        "type": "object",
        "description": "Only `signed` and `should_be_signed` are returned, unless the account uses PDF service v2; then the `signature*` fields are added.",
        "properties": {
          "signed": {
            "type": "boolean",
            "description": "Indicates whether the document is digitally signed",
            "example": true
          },
          "should_be_signed": {
            "type": "boolean",
            "description": "Indicates whether the document should be digitally signed",
            "example": true
          },
          "signature": {
            "type": "string",
            "enum": [
              "signed",
              "unsigned",
              "pending",
              "not_applicable",
              "unknown"
            ],
            "description": "PDF service v2 only. Signature state of the document's PDF.",
            "example": "signed"
          },
          "signature_provider": {
            "type": [
              "string",
              "null"
            ],
            "description": "PDF service v2 only. Provider that signed the PDF.",
            "example": "multicert"
          },
          "signature_error_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "PDF service v2 only. Why the PDF was delivered unsigned (e.g. `credentials_expired`).",
            "example": null
          },
          "signature_updated_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "PDF service v2 only. When the signature state last changed.",
            "example": null
          }
        }
      },
      "V3DigitalSignatureCredentialsErrorResponse": {
        "type": "object",
        "description": "Returned when a record lookup fails (no account provider, or missing/unknown `provider_id`). `errors` is the bare exception message.",
        "properties": {
          "errors": {
            "type": "string",
            "description": "Raw error message — not the usual array-of-objects error shape used elsewhere in this API",
            "example": "Couldn't find DsAccountProvider with [WHERE `ds_account_providers`.`account_id` = ?]"
          }
        }
      },
      "V3DigitalSignatureCredentialsResponse": {
        "type": "object",
        "properties": {
          "client_id": {
            "type": [
              "string",
              "null"
            ],
            "example": "3b897ad6-cce4-4c54-a7e7-2bd00b83ab85"
          },
          "client_secret": {
            "type": "string",
            "enum": [
              "********",
              ""
            ],
            "description": "Never returned in clear. `\"********\"` when a secret is stored, `\"\"` otherwise.",
            "example": "********"
          }
        }
      },
      "V3DigitalSignatureProviderObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "name": {
            "type": "string",
            "example": "Multicert"
          },
          "description": {
            "type": "string",
            "description": "Localized text in the account language. May contain HTML (e.g. an `<a href>` link for Multicert); render or strip it accordingly. Empty string when there is no text for the provider.",
            "example": "Digitally sign your documents using the Electronic Invoice Signing Service (SAFE)."
          },
          "identifier": {
            "type": "string",
            "example": "multicert"
          },
          "grant_type": {
            "type": "string",
            "description": "OAuth grant type used by this provider",
            "example": "client_credentials"
          },
          "url_image": {
            "type": "string",
            "example": "/digital_signatures/providers/multicert-logo.png"
          },
          "url_guide": {
            "type": "string",
            "example": "https://invoicexpress.helpscoutdocs.com/article/347-assinatura-digital-guia-passo-a-passo-para-a-ativacao"
          },
          "url_auth": {
            "type": "string",
            "description": "OAuth authorization URL to opt into this provider",
            "example": "https://preprod.autenticacao.gov.pt/oauth/askauthorization"
          },
          "in_use": {
            "type": "boolean",
            "description": "Whether this provider is the one currently active for the account",
            "example": false
          },
          "expired": {
            "type": [
              "boolean",
              "null"
            ],
            "example": false
          },
          "expiration_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "example": null
          }
        }
      },
      "V3DigitalSignatureValidationErrorResponse": {
        "type": "object",
        "description": "Model validation errors, keyed by attribute (not the usual array-of-objects error shape).",
        "properties": {
          "errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "example": {
              "consent_agreement": [
                "can't be blank"
              ]
            }
          }
        }
      },
      "V3DigitalSignatureSignAcceptedResponse": {
        "type": "object",
        "properties": {
          "signature": {
            "type": "string",
            "enum": [
              "pending"
            ],
            "example": "pending"
          },
          "requested": {
            "type": "boolean",
            "description": "`true` when a new signed PDF was requested from PDF service v2.",
            "example": true
          }
        }
      },
      "V3CiusPtReadyResponse": {
        "type": "object",
        "description": "Returned when the CIUS-PT file is ready. The body is not wrapped.",
        "properties": {
          "key": {
            "type": "string",
            "description": "S3 object key of the generated file.",
            "example": "production/148306/267339734/settled-cius-pt.xml"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Pre-signed S3 download URL, valid for 7 days.",
            "example": "https://invoicexpress-cius-xml.s3.eu-west-1.amazonaws.com/production/148306/267339734/settled-cius-pt.xml?response-content-disposition=attachment&X-Amz-Expires=604800"
          }
        }
      },
      "V3CiusPtProcessingResponse": {
        "type": "object",
        "description": "Returned while the CIUS-PT file is still being generated. Keep polling until the body contains `key` and `url`. Note this is also HTTP `200`, not `202`.",
        "properties": {
          "generating": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "V3CiusAdditionalFieldsResponse": {
        "type": "object",
        "description": "The document's CIUS/EDI additional fields. Every field is always present; each is `null` when no additional fields have been stored for the document yet.",
        "properties": {
          "additional_fields": {
            "type": "object",
            "properties": {
              "order_reference": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "PO-2026-0042"
              },
              "accounting_cost": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "Cost centre 4711"
              },
              "contract_document_reference": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "CT-2026-118"
              },
              "despatch_document_reference": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "DES-2026-0091"
              },
              "originator_document_reference": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "ORIG-2026-0007"
              },
              "actual_delivery_date": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date",
                "example": "2026-06-01"
              }
            }
          }
        }
      },
      "V3CreateCiusAdditionalFieldsRequest": {
        "type": "object",
        "required": [
          "additional_fields"
        ],
        "properties": {
          "additional_fields": {
            "type": "object",
            "description": "All fields are optional, but the `additional_fields` wrapper itself is required. Fields omitted from the payload keep their stored value — this is a partial update, not a replace.",
            "properties": {
              "order_reference": {
                "type": "string",
                "example": "PO-2026-0042"
              },
              "accounting_cost": {
                "type": "string",
                "example": "Cost centre 4711"
              },
              "contract_document_reference": {
                "type": "string",
                "example": "CT-2026-118"
              },
              "despatch_document_reference": {
                "type": "string",
                "example": "DES-2026-0091"
              },
              "originator_document_reference": {
                "type": "string",
                "example": "ORIG-2026-0007"
              },
              "actual_delivery_date": {
                "type": "string",
                "format": "date",
                "description": "Delivery date in `YYYY-MM-DD` format. Any value that cannot be parsed as a date returns `422`.",
                "example": "2026-06-01"
              }
            }
          }
        }
      },
      "V3CiusPtUnauthorizedError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "description": "Returned when the account is in trial, or on a plan without CIUS-PT support.",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "Account is in trial. subscribe in order to have access to this feature"
              }
            ]
          }
        }
      },
      "V3CiusPtNotAcceptableError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "description": "Returned when the document type is not eligible for CIUS-PT (`invalid document type error`) or the document is still a draft (`Invalid document status error`). The messages are translatable (English shown); do not match on the text, use the 406 status.",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "Invalid document status error"
              }
            ]
          }
        }
      },
      "V3CiusPtGenerationError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "description": "Returned when the CIUS-PT file could not be generated. The message is the underlying exception message.",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "Error generating the CIUS-PT file"
              }
            ]
          }
        }
      },
      "V3CiusAdditionalFieldsError": {
        "type": "object",
        "properties": {
          "errors": {
            "type": "array",
            "description": "Returned when `actual_delivery_date` cannot be parsed as a date.",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "invalid date"
              }
            ]
          }
        }
      },
      "V3SocialSecurityError": {
        "type": "object",
        "description": "Error body returned by the Social Security endpoints.",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "No NISS is set for this account yet."
              }
            ]
          }
        }
      },
      "V3SocialSecurityForbiddenError": {
        "type": "object",
        "description": "Returned with HTTP `403` when the API key's user has a role that is not permitted to perform the action.",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            },
            "example": [
              {
                "error": "You do not have permission to perform this action"
              }
            ]
          }
        }
      },
      "V3SocialSecuritySettings": {
        "type": "object",
        "description": "The account's Social Security settings. Always returns all five fields.",
        "properties": {
          "niss": {
            "type": [
              "string",
              "null"
            ],
            "description": "NISS (Social Security identification number), 11 digits, stored without separators. `null` when no settings exist yet.",
            "example": "12345678902"
          },
          "worker_type": {
            "type": "string",
            "enum": [
              "independente",
              "eni"
            ],
            "description": "Worker type. Changes the contribution rate used by the quarterly declaration.",
            "example": "independente"
          },
          "regime": {
            "type": "string",
            "enum": [
              "services",
              "goods",
              "mixed"
            ],
            "description": "Stored and returned only. No calculation reads it.",
            "example": "services"
          },
          "exempt": {
            "type": "boolean",
            "description": "Stored and returned only. No calculation reads it.",
            "example": false
          },
          "special_profile": {
            "type": "string",
            "enum": [
              "none",
              "organized_accounting",
              "accumulation",
              "own_fund"
            ],
            "description": "Stored and returned only. No calculation reads it. `organized_accounting` does not exempt the account from the calculation.",
            "example": "none"
          }
        }
      },
      "V3SocialSecurityResponse": {
        "type": "object",
        "properties": {
          "social_security": {
            "$ref": "#/components/schemas/V3SocialSecuritySettings"
          }
        }
      },
      "V3SocialSecurityCreateRequest": {
        "type": "object",
        "required": [
          "social_security"
        ],
        "description": "Do not send `null` for `worker_type`, `regime`, `exempt` or `special_profile`; the column is not nullable and the API answers 500.",
        "properties": {
          "social_security": {
            "type": "object",
            "required": [
              "niss"
            ],
            "properties": {
              "niss": {
                "type": "string",
                "description": "11 digits, first digit `1` or `2`, valid check digit. Spaces, `-`, `.` and `/` are stripped before validation and storage, so `123-456-789-02` is stored as `12345678902`. Letters make it invalid.",
                "example": "123-456-789-02"
              },
              "worker_type": {
                "type": "string",
                "enum": [
                  "independente",
                  "eni"
                ],
                "description": "Defaults to `independente`.",
                "example": "eni"
              },
              "regime": {
                "type": "string",
                "enum": [
                  "services",
                  "goods",
                  "mixed"
                ],
                "description": "Defaults to `services`. Stored only.",
                "example": "services"
              },
              "exempt": {
                "type": "boolean",
                "description": "Defaults to `false`. Stored only.",
                "example": false
              },
              "special_profile": {
                "type": "string",
                "enum": [
                  "none",
                  "organized_accounting",
                  "accumulation",
                  "own_fund"
                ],
                "description": "Defaults to `none`. Stored only.",
                "example": "none"
              }
            }
          }
        }
      },
      "V3SocialSecurityUpdateRequest": {
        "type": "object",
        "required": [
          "social_security"
        ],
        "description": "Send only the fields to change. Do not send `null` for `worker_type`, `regime`, `exempt` or `special_profile`; the column is not nullable and the API answers 500.",
        "properties": {
          "social_security": {
            "type": "object",
            "properties": {
              "niss": {
                "type": "string",
                "description": "Same normalisation and rules as on create. Validated only when it changes.",
                "example": "123-456-789-02"
              },
              "worker_type": {
                "type": "string",
                "enum": [
                  "independente",
                  "eni"
                ],
                "example": "independente"
              },
              "regime": {
                "type": "string",
                "enum": [
                  "services",
                  "goods",
                  "mixed"
                ],
                "example": "services"
              },
              "exempt": {
                "type": "boolean",
                "example": false
              },
              "special_profile": {
                "type": "string",
                "enum": [
                  "none",
                  "organized_accounting",
                  "accumulation",
                  "own_fund"
                ],
                "example": "none"
              }
            }
          }
        }
      },
      "V3SocialSecurityInternalError": {
        "type": "object",
        "description": "Returned with HTTP `500` when the settings cannot be saved, for example when `null` is sent for `worker_type`, `regime`, `exempt` or `special_profile`. The body is the framework's default error, not the `errors[].error` shape.",
        "properties": {
          "status": {
            "type": "integer",
            "example": 500
          },
          "error": {
            "type": "string",
            "example": "Internal Server Error"
          }
        }
      },
      "V3SocialSecurityDeleteResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "V3SocialSecurityBadRequestError": {
        "type": "object",
        "description": "Returned with HTTP `400` when the body is empty, `{}`, or `social_security` is `null` or `{}`. The body is the framework's default error, not the `errors[].error` shape. Malformed JSON returns `V3SocialSecurityError` instead.",
        "properties": {
          "status": {
            "type": "integer",
            "example": 400
          },
          "error": {
            "type": "string",
            "example": "Bad Request"
          }
        }
      },
      "V3SocialSecurityMonthlyBreakdown": {
        "type": "object",
        "description": "One calendar month of a quarter. A quarter always carries exactly 3 of these, in month order; a month with no invoicing appears with zeros. Each money field of the quarter is the sum of the same field over its 3 months. `services_amount` plus `goods_amount` normally adds up to `total_amount`; they come from different sources and may differ by rounding.",
        "properties": {
          "month": {
            "type": "integer",
            "minimum": 1,
            "maximum": 12,
            "description": "Calendar month number.",
            "example": 5
          },
          "total_amount": {
            "type": "string",
            "description": "Gross invoiced amount of the month before VAT (`total_before_taxes`), as a decimal string (for example `\"500.0\"`). Not a JSON number.",
            "example": "500.0"
          },
          "services_amount": {
            "type": "string",
            "description": "Part of `total_amount` classified as services (invoice lines whose `unit` is not `unit`, `product` or `article`). A heuristic split. Decimal string.",
            "example": "400.0"
          },
          "goods_amount": {
            "type": "string",
            "description": "Part of `total_amount` classified as goods (invoice lines whose `unit` is `unit`, `product` or `article`). A heuristic split. Decimal string.",
            "example": "100.0"
          },
          "document_count": {
            "type": "integer",
            "description": "Number of documents counted in the month.",
            "example": 2
          }
        }
      },
      "V3SocialSecurityQuarter": {
        "type": "object",
        "description": "The totals of one quarter. These are the fields of a quarterly declaration except `year`, `niss` and `worker_type`, which the history endpoint hoists to the year level. Every field whose name starts with `estimated_` is an estimate, not an amount computed by Segurança Social. `total_amount` is the figure to declare.",
        "properties": {
          "quarter": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4,
            "example": 2
          },
          "start_date": {
            "type": "string",
            "format": "date",
            "description": "First day of the quarter.",
            "example": "2026-04-01"
          },
          "end_date": {
            "type": "string",
            "format": "date",
            "description": "Last day of the quarter.",
            "example": "2026-06-30"
          },
          "total_amount": {
            "type": "string",
            "description": "The figure to declare in Segurança Social Direta: the gross amount invoiced in the quarter, before VAT. Decimal string (for example `\"1250.5\"`), not a JSON number. Counts `Invoice`, `SimplifiedInvoice` and `InvoiceReceipt` documents (and legacy documents with no type) with status `sent`, `settled` or `second_copy`, dated inside the quarter.",
            "example": "1250.5"
          },
          "services_amount": {
            "type": "string",
            "description": "Heuristic services share of `total_amount`, from the unit of each invoice line. Normally adds up to `total_amount` together with `goods_amount`, but the two come from different sources (`total_amount` from the document totals, the split from the line subtotals) and may differ by rounding. Decimal string.",
            "example": "1000.5"
          },
          "goods_amount": {
            "type": "string",
            "description": "Heuristic goods share of `total_amount`. Decimal string.",
            "example": "250.0"
          },
          "document_count": {
            "type": "integer",
            "description": "Number of documents counted.",
            "example": 4
          },
          "monthly_breakdown": {
            "type": "array",
            "description": "Always exactly 3 entries, in month order.",
            "minItems": 3,
            "maxItems": 3,
            "items": {
              "$ref": "#/components/schemas/V3SocialSecurityMonthlyBreakdown"
            }
          },
          "contribution_year": {
            "type": "integer",
            "description": "Year whose IAS caps the contribution base. Equals `year`, except for quarter 4, which is declared in January and uses `year + 1`. If that year is not in the IAS table (a future year, or before 2014) the latest known IAS is used (`537.13`, the 2026 value).",
            "example": 2026
          },
          "ias": {
            "type": "string",
            "description": "IAS (Indexante dos Apoios Sociais) of `contribution_year`, as a decimal string without fixed decimals (`\"537.13\"`, `\"522.5\"`). Returned so a client can explain the estimate.",
            "example": "537.13"
          },
          "monthly_base_cap": {
            "type": "string",
            "description": "Cap on the monthly contribution base, 12 times `ias`. Decimal string.",
            "example": "6445.56"
          },
          "estimated_relevant_income": {
            "type": "number",
            "description": "ESTIMATE. `services_amount` x 0.70 + `goods_amount` x 0.20, rounded to 2 decimals. JSON number.",
            "example": 750.35
          },
          "estimated_monthly_payment": {
            "type": "number",
            "description": "ESTIMATE. Contribution for each of the 3 months this declaration bills, not for the quarter. `max(round(min(estimated_relevant_income / 3, monthly_base_cap) x rate, 2), 20.00)`, with rate 0.214 for `independente` and 0.252 for `eni`. Never below the 20.00 monthly minimum, so a quarter with no invoicing still shows `20.0`. JSON number.",
            "example": 53.52
          },
          "submitted_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the account recorded a self-report for this quarter, otherwise `null`. It can be set on a quarter that is still open.",
            "example": null
          }
        }
      },
      "V3SocialSecurityQuarterlyDeclaration": {
        "description": "One quarter's declaration. Same fields as `V3SocialSecurityQuarter`, plus `year`, `niss` and `worker_type`.",
        "allOf": [
          {
            "type": "object",
            "properties": {
              "year": {
                "type": "integer",
                "example": 2026
              },
              "niss": {
                "type": "string",
                "description": "Read live from the current settings, so a correction shows up at once, even on a past quarter.",
                "example": "12345678902"
              },
              "worker_type": {
                "type": "string",
                "enum": [
                  "independente",
                  "eni"
                ],
                "description": "Read live from the current settings. Selects the contribution rate.",
                "example": "independente"
              }
            }
          },
          {
            "$ref": "#/components/schemas/V3SocialSecurityQuarter"
          }
        ]
      },
      "V3SocialSecurityYearGroup": {
        "type": "object",
        "description": "All the listed quarters of one year. `niss` and `worker_type` appear here, not on each quarter.",
        "properties": {
          "year": {
            "type": "integer",
            "example": 2026
          },
          "quarters": {
            "type": "array",
            "description": "Newest quarter first.",
            "items": {
              "$ref": "#/components/schemas/V3SocialSecurityQuarter"
            }
          },
          "niss": {
            "type": "string",
            "description": "Read live from the current settings.",
            "example": "12345678902"
          },
          "worker_type": {
            "type": "string",
            "enum": [
              "independente",
              "eni"
            ],
            "description": "Read live from the current settings.",
            "example": "independente"
          }
        }
      },
      "V3SocialSecurityReport": {
        "type": "object",
        "description": "A quarterly self-report, identified by `year` + `quarter` (there is no id). At most one per account, year and quarter. A personal tracking record; nothing is sent to Segurança Social.",
        "properties": {
          "year": {
            "type": "integer",
            "description": "Year of the report. Set on create; ignored on update. Supported range `1583` to `9999`, as on the quarterly declaration endpoints, except `year` `9999` with `quarter` `4` when `reported_at` is set (`500`, nothing is saved); the API does not validate it, and a value outside the range may answer `500`.",
            "example": 2026
          },
          "quarter": {
            "type": "integer",
            "minimum": 1,
            "maximum": 4,
            "description": "Quarter, `1` to `4`. Set on create; ignored on update.",
            "example": 2
          },
          "reported_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the quarter was declared in Segurança Social Direta, `null` when not set. Returned as ISO 8601 in the account's time zone (for example `+01:00`), whatever offset was sent. Setting, changing or clearing it also sets or clears `submitted_at` of that quarter on the quarterly declaration endpoints.",
            "example": "2026-07-15T20:08:03+01:00"
          },
          "estimated_monthly_payment": {
            "type": [
              "string",
              "null"
            ],
            "description": "The monthly payment that was estimated, as a decimal string (not a number), `0` to `9999999999.99`, rounded to 2 places, in the shortest form but always with at least one decimal digit (`\"53.53\"`, `\"55.1\"`, `\"70.0\"`). `null` when not set.",
            "example": "53.53"
          },
          "monthly_payment": {
            "type": [
              "string",
              "null"
            ],
            "description": "The monthly payment actually charged, as a decimal string (not a number), `0` to `9999999999.99`, rounded to 2 places, in the shortest form but always with at least one decimal digit (`\"53.53\"`, `\"55.1\"`, `\"70.0\"`). `null` when not set.",
            "example": "55.1"
          }
        }
      },
      "V3SocialSecurityReportResponse": {
        "type": "object",
        "properties": {
          "social_security_report": {
            "$ref": "#/components/schemas/V3SocialSecurityReport"
          }
        }
      },
      "V3SocialSecurityReportCreateRequest": {
        "type": "object",
        "required": [
          "social_security_report"
        ],
        "properties": {
          "social_security_report": {
            "type": "object",
            "required": [
              "year",
              "quarter"
            ],
            "properties": {
              "year": {
                "type": "integer",
                "description": "Required. Supported range `1583` to `9999`, except `year` `9999` with `quarter` `4` when `reported_at` is set (`500`, nothing is saved); a value outside the range may answer `500`.",
                "example": 2026
              },
              "quarter": {
                "type": "integer",
                "minimum": 1,
                "maximum": 4,
                "description": "Required, `1` to `4`.",
                "example": 2
              },
              "reported_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "Optional. Sets `submitted_at` of the quarter's declaration.",
                "example": "2026-07-15T19:08:03Z"
              },
              "estimated_monthly_payment": {
                "type": [
                  "number",
                  "string",
                  "null"
                ],
                "description": "Optional, `0` to `9999999999.99`. Rounded to 2 places and returned as a decimal string with at least one decimal digit (`70` is returned as `\"70.0\"`).",
                "example": 53.53
              },
              "monthly_payment": {
                "type": [
                  "number",
                  "string",
                  "null"
                ],
                "description": "Optional, `0` to `9999999999.99`. Rounded to 2 places and returned as a decimal string with at least one decimal digit (`70` is returned as `\"70.0\"`).",
                "example": 55.1
              }
            }
          }
        }
      },
      "V3SocialSecurityReportUpdateRequest": {
        "type": "object",
        "required": [
          "social_security_report"
        ],
        "description": "Send only the fields to change. `year` and `quarter` in the body are ignored (the URL identifies the report); there is no way to move a report to another quarter.",
        "properties": {
          "social_security_report": {
            "type": "object",
            "properties": {
              "reported_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time",
                "description": "A new value sets `submitted_at` of the quarter to it; `null` clears it. Omitted or unchanged leaves it untouched.",
                "example": "2026-08-01T10:00:00Z"
              },
              "estimated_monthly_payment": {
                "type": [
                  "number",
                  "string",
                  "null"
                ],
                "description": "`0` to `9999999999.99`. `null` clears it.",
                "example": 53.53
              },
              "monthly_payment": {
                "type": [
                  "number",
                  "string",
                  "null"
                ],
                "description": "`0` to `9999999999.99`. `null` clears it.",
                "example": 60.46
              }
            }
          }
        }
      },
      "V3DocumentGlobalDiscount": {
        "type": [
          "object",
          "null"
        ],
        "description": "Document-level discount, or null when there is none.",
        "properties": {
          "value_type": {
            "type": "string",
            "enum": [
              "percentage",
              "absolute"
            ],
            "example": "percentage"
          },
          "value": {
            "type": "number",
            "example": 10
          }
        },
        "example": null
      },
      "V3DocumentRawOwnerInvoice": {
        "type": "string",
        "description": "Conditional — only present when set. Reference to an original document issued outside InvoiceXpress (isolated credit/debit notes), in the form `\"<TYPE> <SERIE>/<NUMBER>\"`.",
        "example": "FT 2026/253"
      },
      "V3DocumentCurrency": {
        "type": [
          "object",
          "null"
        ],
        "description": "Document currency when one was set (multi-currency plans); null otherwise.",
        "properties": {
          "name": {
            "type": "string",
            "example": "US Dollar"
          },
          "code": {
            "type": "string",
            "example": "USD"
          },
          "symbol": {
            "type": "string",
            "example": "$"
          }
        },
        "example": null
      },
      "V3DocumentQrCodeField": {
        "type": "string",
        "description": "Conditional — never present on API-key requests. Only returned to the InvoiceXpress web app, for non-draft documents with a real ATCUD once the QR code image has been generated. Public URL of the QR code image.",
        "example": "https://example.com/qr_codes/264663413.png"
      },
      "V3DocumentDigitalSignedField": {
        "type": "boolean",
        "description": "Conditional — never present on API-key requests. Only returned to the InvoiceXpress web app; whether the document PDF is digitally signed.",
        "example": false
      },
      "V3DocumentIncludePaymentReferenceField": {
        "type": "boolean",
        "description": "Conditional — never present on API-key requests. Only returned to the InvoiceXpress web app for draft (or deleted) documents of a type that supports a Multibanco reference, when the plan includes MB, an MB provider is configured and the document has no MB reference yet. Reflects the account's \"add payment reference by default\" preference.",
        "example": false
      },
      "V3DocumentPhoneCountryCode": {
        "type": "string",
        "description": "International calling code for the phone/mobile number (e.g. `+351`); empty string when unset.",
        "example": "+351"
      },
      "V3DocumentPhoneIndicativePrinted": {
        "type": "boolean",
        "description": "Whether the document PDF prints `phone` behind `phone_country_code`.",
        "example": false
      },
      "V3DocumentAccountFooter": {
        "type": [
          "string",
          "null"
        ],
        "description": "Document footer text — the document series' configured footer when set, otherwise the account's invoice footer.",
        "example": null
      },
      "V3InvoicesQueryParams": {
        "type": "object",
        "description": "Optional filters and pagination for listing invoices (sent as query string parameters). Archived documents are excluded unless `archived=true` is sent. Date bounds accept ISO 8601 (`2024-01-31`) or `dd/mm/yyyy` (`31/01/2024`); an unparseable date bound is ignored.",
        "properties": {
          "language": {
            "type": "string",
            "description": "Language of the response"
          },
          "per_page": {
            "type": "integer",
            "default": 10,
            "description": "Number of items per page. Takes precedence over `items_per_page` and `page_items`. Defaults to 10."
          },
          "items_per_page": {
            "type": "integer",
            "default": 10,
            "description": "Alias of `per_page`. Defaults to 10."
          },
          "page_items": {
            "type": "integer",
            "default": 10,
            "description": "Alias of `per_page`. Defaults to 10."
          },
          "page": {
            "type": "integer",
            "default": 1,
            "description": "Page number"
          },
          "batch_id": {
            "type": "string",
            "description": "Only invoices created by this import batch (an `id` from `GET /api/v3/invoices/batches`).",
            "example": "123"
          },
          "id": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Filter by one or more document ids. Must be sent in array form (`id[]=value`, repeat for several values); a scalar `id=value` is silently ignored.",
            "example": [
              "541897"
            ]
          },
          "except_id": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Exclude these document ids. Must be sent in array form (`except_id[]=value`, repeat for several values); a scalar `except_id=value` is silently ignored.",
            "example": [
              "541897"
            ]
          },
          "sort": {
            "type": "string",
            "description": "Field to sort by"
          },
          "sort_order": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "description": "Order of sorting (asc/desc)"
          },
          "text": {
            "type": "string",
            "description": "Text to search for"
          },
          "non_archived": {
            "type": "boolean",
            "description": "Include non-archived documents. When neither `archived` nor `non_archived` is true, only non-archived documents are returned."
          },
          "archived": {
            "type": "boolean",
            "description": "Include archived documents (excluded by default). Send together with `non_archived=true` to get both."
          },
          "reference": {
            "type": "string",
            "description": "Reference identifier"
          },
          "show_iva": {
            "type": "boolean",
            "description": "Show IVA"
          },
          "type": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Document type filter. Must be sent in array form (`type[]=value`, repeat for several values); a scalar `type=value` is silently ignored.",
            "example": [
              "Invoice"
            ]
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Status filter. Must be sent in array form (`status[]=value`, repeat for several values); a scalar `status=value` is silently ignored.",
            "example": [
              "draft"
            ]
          },
          "client_id": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Client ID filter. Must be sent in array form (`client_id[]=value`, repeat for several values); a scalar `client_id=value` is silently ignored.",
            "example": [
              "541897"
            ]
          },
          "plugin": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Plugin filter. Must be sent in array form (`plugin[]=value`, repeat for several values); a scalar `plugin=value` is silently ignored.",
            "example": [
              "541897123-asdasdasd-zxcas123"
            ]
          },
          "serie_name": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Serie name filter. Must be sent in array form (`serie_name[]=value`, repeat for several values); a scalar `serie_name=value` is silently ignored.",
            "example": [
              "SerieA"
            ]
          },
          "date[from]": {
            "type": "string",
            "description": "Date range start (ISO `yyyy-mm-dd` or `dd/mm/yyyy`)"
          },
          "date[to]": {
            "type": "string",
            "description": "Date range end (ISO `yyyy-mm-dd` or `dd/mm/yyyy`)"
          },
          "due_date[from]": {
            "type": "string",
            "description": "Due date range start (ISO `yyyy-mm-dd` or `dd/mm/yyyy`)"
          },
          "due_date[to]": {
            "type": "string",
            "description": "Due date range end (ISO `yyyy-mm-dd` or `dd/mm/yyyy`)"
          },
          "total_before_taxes[from]": {
            "type": "number",
            "description": "Total before taxes range start"
          },
          "total_before_taxes[to]": {
            "type": "number",
            "description": "Total before taxes range end"
          },
          "total_with_taxes[from]": {
            "type": "number",
            "description": "Total with taxes range start"
          },
          "total_with_taxes[to]": {
            "type": "number",
            "description": "Total with taxes range end"
          }
        }
      },
      "V3GuideAddress": {
        "type": "object",
        "description": "Structured address. Used only by Portuguese accounts, where it is required with all four fields filled in; foreign accounts ignore it and use `load_site` / `delivery_site` instead.",
        "required": [
          "detail",
          "city",
          "postal_code",
          "country"
        ],
        "properties": {
          "detail": {
            "type": "string",
            "description": "Street address. Line breaks are re-inserted roughly every 35 characters before storing.",
            "example": "123 Loading Street"
          },
          "city": {
            "type": "string",
            "example": "Lisbon"
          },
          "postal_code": {
            "type": "string",
            "example": "1000-001"
          },
          "country": {
            "type": "string",
            "description": "English country name, matched against the `name` of the `countries` list returned by `GET /api/v3/{guides-type}/new`. An unknown name falls back to Portugal.",
            "example": "Portugal"
          }
        }
      },
      "V3EstimatesQueryParams": {
        "type": "object",
        "description": "Optional filters and pagination for listing estimates (sent as query string parameters).",
        "properties": {
          "language": {
            "type": "string",
            "description": "Language of the response",
            "example": "pt"
          },
          "items_per_page": {
            "type": "integer",
            "description": "Number of items per page",
            "example": 10
          },
          "page": {
            "type": "integer",
            "description": "Page number",
            "example": 1
          },
          "id": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Filter by one or more document ids",
            "example": [
              "541897"
            ]
          },
          "except_id": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Exclude these document ids",
            "example": [
              "541897"
            ]
          },
          "sort": {
            "type": "string",
            "description": "Field to sort by",
            "example": "date"
          },
          "sort_order": {
            "type": "string",
            "enum": [
              "asc",
              "desc"
            ],
            "description": "Order of sorting (asc/desc)",
            "example": "desc"
          },
          "text": {
            "type": "string",
            "description": "Text to search for",
            "example": "John Doe"
          },
          "non_archived": {
            "type": "boolean",
            "description": "Filter for non-archived items",
            "example": true
          },
          "archived": {
            "type": "boolean",
            "description": "Filter for archived items",
            "example": false
          },
          "reference": {
            "type": "string",
            "description": "Reference identifier",
            "example": "PO-999"
          },
          "type": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "Quote",
                "Proforma",
                "FeesNote"
              ]
            },
            "description": "Document type filter",
            "example": [
              "Quote"
            ]
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "draft",
                "sent",
                "accepted",
                "refused",
                "canceled",
                "deleted"
              ]
            },
            "description": "Status filter",
            "example": [
              "draft"
            ]
          },
          "client_id": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Client id filter",
            "example": [
              "541897"
            ]
          },
          "serie_name": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Serie name filter",
            "example": [
              "SerieA"
            ]
          },
          "date[from]": {
            "type": "string",
            "format": "date",
            "description": "Document date range start",
            "example": "2026-04-27"
          },
          "date[to]": {
            "type": "string",
            "format": "date",
            "description": "Document date range end",
            "example": "2026-04-27"
          },
          "valid_to[from]": {
            "type": "string",
            "format": "date",
            "description": "Valid-until (expiry) date range start",
            "example": "2026-04-27"
          },
          "valid_to[to]": {
            "type": "string",
            "format": "date",
            "description": "Valid-until (expiry) date range end",
            "example": "2026-04-27"
          },
          "total_before_taxes[from]": {
            "type": "number",
            "description": "Total before taxes range start"
          },
          "total_before_taxes[to]": {
            "type": "number",
            "description": "Total before taxes range end"
          },
          "total_with_taxes[from]": {
            "type": "number",
            "description": "Total with taxes range start"
          },
          "total_with_taxes[to]": {
            "type": "number",
            "description": "Total with taxes range end"
          }
        }
      },
      "V3EstimateIndexRange": {
        "type": "object",
        "properties": {
          "from": {
            "type": [
              "string",
              "number"
            ]
          },
          "to": {
            "type": [
              "string",
              "number"
            ]
          }
        }
      },
      "client": {
        "type": "object",
        "description": "Optional. When omitted, the estimate is issued to Consumidor Final.",
        "properties": {
          "name": {
            "type": "string",
            "example": "Test Client API",
            "maxLength": 100
          },
          "email": {
            "type": "string",
            "example": "client@example.com",
            "maxLength": 254
          },
          "fiscal_id": {
            "type": "string",
            "example": "987654321",
            "maxLength": 255
          },
          "address": {
            "type": "string",
            "example": "456 Client Street",
            "description": "Street address as a flat string (not a nested object)."
          },
          "postal_code": {
            "type": "string",
            "example": "2000-002",
            "maxLength": 255
          },
          "city": {
            "type": "string",
            "example": "Porto",
            "maxLength": 255
          },
          "country": {
            "type": "string",
            "example": "Portugal",
            "maxLength": 255,
            "description": "Fiscal country of the client."
          },
          "address_country": {
            "type": "string",
            "example": "Portugal",
            "description": "Country of the postal address, when different from the fiscal country; takes priority over `country` for the address."
          }
        }
      },
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "example": "Test Service",
              "maxLength": 60,
              "description": "Maximum 60 characters. Longer values are rejected with 422 (\"Code for the item is too long\")."
            },
            "description": {
              "type": "string",
              "example": "Service description",
              "maxLength": 200,
              "description": "Maximum 200 characters and at most 20 lines. Longer values are rejected with 422."
            },
            "unit_price": {
              "type": "number",
              "example": 100
            },
            "unit": {
              "type": "string",
              "example": "service"
            },
            "quantity": {
              "type": "number",
              "example": 1
            },
            "discount": {
              "type": "number",
              "example": 0
            },
            "tax": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "example": "IVA23"
                }
              }
            }
          }
        }
      },
      "V3ClientWritableFields": {
        "type": "object",
        "description": "Client fields accepted on create and update. Any other key inside `client` is ignored.\nSending `initial_balance` inside `client` is not supported: the request fails with HTTP 500.\nUse `PUT /api/v3/clients/{id}/initial_balance` instead.",
        "properties": {
          "name": {
            "type": "string",
            "example": "John Doe",
            "maxLength": 100
          },
          "code": {
            "type": "string",
            "example": "12345",
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "language": {
            "type": "string",
            "example": "pt",
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "email": {
            "type": "string",
            "example": "john.doe@invoicexpress.com",
            "maxLength": 254
          },
          "address": {
            "type": "string",
            "example": "Avenida da República, Lisboa",
            "description": "No enforced character limit (text column)."
          },
          "city": {
            "type": "string",
            "example": "Lisboa",
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "postal_code": {
            "type": "string",
            "example": "1050-555",
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "fiscal_id": {
            "type": "string",
            "example": "123456789",
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "website": {
            "type": "string",
            "example": "www.invoicexpress.com",
            "maxLength": 60
          },
          "country": {
            "type": "string",
            "example": "Portugal",
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "address_country": {
            "type": [
              "string",
              "null"
            ],
            "example": "PT",
            "description": "ISO country code of the client's address. Stored as sent (an unknown code is kept as received); send it empty or `null` to clear it. Omit the key to leave the stored value unchanged."
          },
          "phone": {
            "type": "string",
            "example": "963214569",
            "maxLength": 20
          },
          "phone_country_id": {
            "type": "integer",
            "example": 1
          },
          "mobile": {
            "type": "string",
            "example": "999999999",
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "mobile_country_id": {
            "type": "integer",
            "example": 1
          },
          "fax": {
            "type": "string",
            "example": "213456789",
            "maxLength": 20
          },
          "preferred_contact": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "example": "Bruce Norris",
                "maxLength": 255,
                "description": "Contact-level name has no length validation, unlike the client-level `name` (max 100); the limit shown is the database default."
              },
              "email": {
                "type": "string",
                "example": "bruce.norris@invoicexpress.com",
                "maxLength": 255,
                "description": "Contact-level email allows one character more than the client-level `email` (max 254)."
              },
              "phone": {
                "type": "string",
                "example": "213456789",
                "maxLength": 255,
                "description": "Contact-level phone has no length validation, unlike the client-level `phone` (max 20); the limit shown is the database default."
              },
              "phone_country_id": {
                "type": "integer",
                "example": 1
              },
              "mobile": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "minLength": 4,
                "maxLength": 14,
                "description": "Digits only (4-14). Validated against /\\A\\d{4,14}\\z/."
              },
              "mobile_country_id": {
                "type": "integer",
                "example": 1
              }
            }
          },
          "observations": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "description": "No enforced character limit (text column)."
          },
          "send_options": {
            "type": "integer",
            "example": 1
          },
          "payment_days": {
            "type": "integer",
            "example": 0
          },
          "tax_exemption_code": {
            "type": "string",
            "example": "M00",
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "payment_mechanism": {
            "type": "string",
            "example": "MB",
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "currency_id": {
            "type": "integer",
            "example": 1
          }
        }
      },
      "V3ClientObject": {
        "type": "object",
        "description": "Client as returned by show, create, update, archive and unarchive. `country` is omitted when the client has none.\nThese fields fall back to the account's own value when the client has none of its own:\n`language`, `observations`, `send_options`, `document_copies` (same value as `send_options`),\n`payment_days`, `tax_exemption_code`, `payment_mechanism` and `currency_id`.\n`use_account_settings` is `true` when the client has none of these set itself.",
        "properties": {
          "id": {
            "type": "integer",
            "example": 191880320
          },
          "name": {
            "type": "string",
            "example": "John Doe",
            "maxLength": 100
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "example": "JS",
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "language": {
            "type": "string",
            "example": "en",
            "maxLength": 255,
            "description": "Falls back to the account language. Maximum length is the database default, not an enforced business rule."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "example": "john.doe@invoicexpress.com",
            "maxLength": 254
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "example": "Avenida da República, Lisboa",
            "description": "No enforced character limit (text column)."
          },
          "city": {
            "type": [
              "string",
              "null"
            ],
            "example": "Lisboa",
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "postal_code": {
            "type": [
              "string",
              "null"
            ],
            "example": "1050-555",
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "fiscal_id": {
            "type": [
              "string",
              "null"
            ],
            "example": "123456789",
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "website": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 60
          },
          "country": {
            "type": "string",
            "example": "Portugal",
            "maxLength": 255,
            "description": "The client's stored `country` (fiscal country). Omitted when the client has none. Maximum length is the database default, not an enforced business rule."
          },
          "address_country": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO country code of the address: the stored address country, else the client's country, else the account's tax location, else `PT`.",
            "example": "PT"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 20
          },
          "phone_country_id": {
            "type": [
              "integer",
              "null"
            ],
            "example": 1
          },
          "mobile": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255,
            "description": "Maximum length is the database default, not an enforced business rule."
          },
          "mobile_country_id": {
            "type": [
              "integer",
              "null"
            ],
            "example": null
          },
          "fax": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 20
          },
          "preferred_contact": {
            "type": "object",
            "description": "Preferred contact info. May be an empty object when no contact is set.",
            "properties": {
              "name": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "maxLength": 255,
                "description": "Contact-level name has no length validation, unlike the client-level `name` (max 100); the limit shown is the database default."
              },
              "email": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "maxLength": 255,
                "description": "Contact-level email allows one character more than the client-level `email` (max 254)."
              },
              "phone": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "maxLength": 255,
                "description": "Contact-level phone has no length validation, unlike the client-level `phone` (max 20); the limit shown is the database default."
              },
              "phone_country_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": null
              },
              "mobile": {
                "type": [
                  "string",
                  "null"
                ],
                "example": null,
                "minLength": 4,
                "maxLength": 14,
                "description": "Digits only (4-14). Validated against /\\A\\d{4,14}\\z/."
              },
              "mobile_country_id": {
                "type": [
                  "integer",
                  "null"
                ],
                "example": null
              }
            }
          },
          "observations": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "description": "Falls back to the account observations. No enforced character limit (text column)."
          },
          "open_account_link": {
            "type": "string",
            "example": "http://www.app.invoicexpress.com/suppliers/47888a650591050dfc40e4511fe9da18db165cb4"
          },
          "document_copies": {
            "type": [
              "integer",
              "null"
            ],
            "example": null,
            "description": "Same value as `send_options` (client value, else the account's)."
          },
          "send_options": {
            "type": [
              "integer",
              "null"
            ],
            "example": null,
            "description": "Falls back to the account value."
          },
          "payment_days": {
            "type": [
              "integer",
              "null"
            ],
            "example": null,
            "description": "Falls back to the account value."
          },
          "tax_exemption_code": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255,
            "description": "Falls back to the account value. Maximum length is the database default, not an enforced business rule."
          },
          "payment_mechanism": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255,
            "description": "Falls back to the account value. Maximum length is the database default, not an enforced business rule."
          },
          "currency_id": {
            "type": "integer",
            "example": 1,
            "description": "Falls back to the account currency."
          },
          "use_account_settings": {
            "type": "boolean",
            "example": true
          },
          "consumidor_final": {
            "type": "boolean",
            "example": false
          },
          "can_be_deleted": {
            "type": "boolean",
            "readOnly": true,
            "example": false,
            "description": "`true` when the client has no documents other than deleted ones, so `DELETE` will succeed. Drafts and canceled documents count. A client that cannot be deleted can be archived instead."
          },
          "archived": {
            "type": "boolean",
            "readOnly": true,
            "example": false,
            "description": "`true` when the client is archived. Change it with the archive and unarchive endpoints; it is ignored on create and update."
          },
          "archived_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "readOnly": true,
            "example": null,
            "description": "When the client was archived, or `null` when it is not archived."
          }
        }
      },
      "V3ClientSuggestionItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "43559f947827f919d8dc1671c2b0008c",
            "description": "Encrypted client token (client id + version), not the numeric id."
          },
          "name": {
            "type": "string",
            "example": "John Doe"
          },
          "fiscal_id": {
            "type": "string",
            "example": "228899331"
          },
          "version": {
            "type": "integer",
            "example": 1
          },
          "raw_id": {
            "type": "string",
            "example": "191880320",
            "description": "The numeric client id, as a string."
          }
        }
      },
      "V3InitialBalanceObject": {
        "type": "object",
        "properties": {
          "value": {
            "type": "number",
            "example": 123
          },
          "date": {
            "type": "string",
            "format": "date",
            "example": "2024-01-01"
          },
          "observation": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          }
        }
      },
      "V3RegularizationItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 97676682
          },
          "number": {
            "type": "string",
            "example": "NR00012345"
          },
          "value": {
            "type": "number",
            "example": 123.45
          },
          "date": {
            "type": "string",
            "format": "date",
            "example": "2023-08-24"
          },
          "observation": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          }
        }
      },
      "V3TreasuryMovementObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 123456
          },
          "value": {
            "type": "number",
            "example": 123.45
          },
          "movement_type": {
            "type": "string",
            "enum": [
              "Payment",
              "Reimbursement",
              "InitialBalance",
              "Regularization"
            ],
            "example": "Reimbursement"
          },
          "payment_method": {
            "type": [
              "string",
              "null"
            ],
            "example": "MB"
          },
          "date": {
            "type": "string",
            "format": "date",
            "example": "2023-04-28"
          }
        }
      },
      "V3AccountObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 148306
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "example": "Avenida Duque D'Avila, Saldanha",
            "maxLength": 210,
            "description": "Values longer than 210 characters are rejected with HTTP 422."
          },
          "address_country": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO country code of the address",
            "example": "PT"
          },
          "at_communication_type": {
            "type": [
              "string",
              "null"
            ],
            "example": "manual",
            "maxLength": 255
          },
          "at_subuser": {
            "type": [
              "string",
              "null"
            ],
            "example": "12345689/0",
            "maxLength": 255
          },
          "at_configured": {
            "type": "boolean",
            "example": true
          },
          "billing_address": {
            "type": [
              "string",
              "null"
            ],
            "example": "Avenida Duque D'Avila, Saldanha",
            "maxLength": 255
          },
          "billing_city": {
            "type": [
              "string",
              "null"
            ],
            "example": "Lisbon",
            "maxLength": 255
          },
          "billing_country_id": {
            "type": [
              "integer",
              "null"
            ],
            "example": 1
          },
          "billing_email": {
            "type": [
              "string",
              "null"
            ],
            "example": "tito.reis@visma.com",
            "maxLength": 255
          },
          "billing_fiscal_id": {
            "type": [
              "string",
              "null"
            ],
            "example": "999999990",
            "maxLength": 255
          },
          "billing_organization_name": {
            "type": [
              "string",
              "null"
            ],
            "example": "invoicexpress",
            "maxLength": 255
          },
          "billing_postal_code": {
            "type": [
              "string",
              "null"
            ],
            "example": "1500-555",
            "maxLength": 255
          },
          "billing_address_country": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO country code of the billing address",
            "example": "PT"
          },
          "can_change_nif": {
            "type": "boolean",
            "example": false
          },
          "capital_social": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255
          },
          "city": {
            "type": [
              "string",
              "null"
            ],
            "example": "Lisbon",
            "maxLength": 50,
            "description": "Values longer than 50 characters are rejected with HTTP 422."
          },
          "conservatoria": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255
          },
          "currency_id": {
            "type": [
              "integer",
              "null"
            ],
            "example": 1
          },
          "decimal_marker": {
            "type": [
              "string",
              "null"
            ],
            "example": ",",
            "maxLength": 255
          },
          "documents_from_last_year": {
            "type": "boolean",
            "example": false
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "example": "tito.reis@visma.com",
            "maxLength": 255
          },
          "fiscal_id": {
            "type": [
              "string",
              "null"
            ],
            "example": "999999990",
            "maxLength": 255
          },
          "fiscal_region": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "iva_caixa": {
            "type": "boolean",
            "example": false
          },
          "language": {
            "type": "string",
            "example": "en",
            "maxLength": 4
          },
          "logo_url": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "observations": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 400,
            "description": "Values longer than 400 characters are rejected with HTTP 422."
          },
          "organization_name": {
            "type": [
              "string",
              "null"
            ],
            "example": "invoicexpress",
            "maxLength": 100,
            "description": "Values longer than 100 characters are rejected with HTTP 422."
          },
          "payment_days": {
            "type": [
              "integer",
              "null"
            ],
            "example": null
          },
          "payment_mechanism": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255
          },
          "postal_code": {
            "type": [
              "string",
              "null"
            ],
            "example": "1500-555",
            "maxLength": 255
          },
          "send_options": {
            "type": [
              "integer",
              "null"
            ],
            "example": null
          },
          "state": {
            "type": "string",
            "example": "active",
            "maxLength": 255
          },
          "tax_exemption_code": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255
          },
          "tax_location_id": {
            "type": [
              "integer",
              "null"
            ],
            "example": 1
          },
          "trial": {
            "type": "boolean",
            "example": false
          }
        }
      },
      "V3BillingHistoryItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "sequence_number": {
            "type": "string",
            "example": "1/Example"
          },
          "date": {
            "type": "string",
            "example": "2025-03-03T05:34:00+00:00"
          },
          "due_date": {
            "type": "string",
            "example": "2025-03-03T05:34:00+00:00"
          },
          "total_before_taxes": {
            "type": "string",
            "example": "24.0"
          },
          "total_taxes": {
            "type": "string",
            "example": "5.52"
          },
          "total": {
            "type": "string",
            "example": "29.52"
          },
          "type": {
            "type": "string",
            "example": "Invoice"
          },
          "permalink": {
            "type": "string",
            "example": "http://environmet_host/documents/8375949084bf77f1d0b4e5180da412a4335d66f7"
          }
        }
      },
      "account": {
        "type": "object",
        "required": [
          "organization_name",
          "fiscal_id",
          "address",
          "postal_code",
          "city"
        ],
        "properties": {
          "organization_name": {
            "type": "string",
            "example": "Strong Security",
            "maxLength": 100,
            "description": "Values longer than 100 characters are rejected with HTTP 422."
          },
          "fiscal_id": {
            "type": "string",
            "example": "123456789",
            "maxLength": 255,
            "description": "Required. Missing or blank is rejected with 422 (\"VAT Number can't be blank\")."
          },
          "address": {
            "type": "string",
            "example": "Avenida da Liberdade",
            "maxLength": 210,
            "description": "Required. Missing or blank is rejected with 422 (\"Address can't be blank\"); values longer than 210 characters are rejected with HTTP 422."
          },
          "postal_code": {
            "type": "string",
            "example": "1250-144",
            "maxLength": 255,
            "description": "Required. Missing or blank is rejected with 422 (\"Postal code can't be blank\")."
          },
          "city": {
            "type": "string",
            "example": "Lisboa",
            "maxLength": 50,
            "description": "Required. Missing or blank is rejected with 422 (\"City can't be blank\"); values longer than 50 characters are rejected with HTTP 422."
          },
          "language": {
            "type": "string",
            "example": "pt",
            "maxLength": 4
          }
        }
      },
      "V3ATCommunicationHistoryItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "document_id": {
            "type": "integer",
            "example": 1
          },
          "sequence_number": {
            "type": "string",
            "example": "1/Example"
          },
          "document_type": {
            "type": "string",
            "example": "Invoice"
          },
          "communication_status": {
            "type": "string",
            "example": "sent"
          },
          "request_sent_at": {
            "type": "string",
            "example": "2025-03-03T05:34:00+00:00"
          },
          "response_code": {
            "type": "integer",
            "example": 0
          },
          "response_message": {
            "type": "string",
            "example": "Operação efetuada com sucesso."
          }
        }
      },
      "V3AccountUserItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 147436
          },
          "email": {
            "type": "string",
            "example": "tito.reis@visma.com",
            "maxLength": 255
          },
          "role": {
            "type": "string",
            "example": "administrator"
          },
          "owner": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "V3CollectionAlertObject": {
        "type": "object",
        "description": "When `GET` is called with a `client_id` whose client has no collection alert configuration, only `client_has_email` is returned.",
        "properties": {
          "configurable": {
            "type": "string",
            "example": "Client"
          },
          "frequency": {
            "type": "string",
            "enum": [
              "disabled",
              "biweekly",
              "weekly",
              "first_week",
              "last_week"
            ],
            "example": "biweekly"
          },
          "weekday": {
            "type": "string",
            "enum": [
              "monday",
              "tuesday",
              "wednesday",
              "thursday",
              "friday"
            ],
            "example": "monday"
          },
          "period": {
            "type": "string",
            "enum": [
              "morning",
              "afternoon"
            ],
            "example": "morning"
          },
          "due": {
            "type": "string",
            "enum": [
              "before_overdue",
              "after_overdue"
            ],
            "example": "before_overdue"
          },
          "email": {
            "type": "boolean",
            "example": true
          },
          "sms": {
            "type": "boolean",
            "example": false
          },
          "email_template": {
            "type": "string",
            "example": "This is an email\nwith a break line"
          },
          "sms_template": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "client_has_email": {
            "type": "boolean",
            "example": true,
            "description": "Whether the client has a contact email."
          }
        }
      },
      "V3MappingFieldEntry": {
        "type": "object",
        "properties": {
          "col": {
            "type": [
              "string",
              "null"
            ],
            "example": "A"
          },
          "field_name": {
            "type": [
              "string",
              "null"
            ],
            "example": "date"
          },
          "required": {
            "type": "boolean",
            "example": false
          },
          "ignore": {
            "type": "boolean",
            "example": false
          },
          "example": {
            "type": [
              "string",
              "null"
            ],
            "example": "2024-01-15"
          }
        }
      },
      "V3CellEntry": {
        "type": "object",
        "properties": {
          "cell": {
            "type": "string",
            "example": "A"
          },
          "field_name": {
            "type": "string",
            "example": "date"
          },
          "example": {
            "type": "string",
            "example": "2024-01-15"
          }
        }
      },
      "V3ItemTax": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "IVA23"
          },
          "value": {
            "type": "number",
            "example": 23
          }
        }
      },
      "V3ItemObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "code": {
            "type": "string",
            "example": "Item name",
            "maxLength": 60
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "example": "Item description",
            "maxLength": 200
          },
          "unit_price": {
            "type": "number",
            "example": 9.99
          },
          "rrp": {
            "type": "number",
            "example": 12.29
          },
          "unit": {
            "type": "string",
            "example": "service",
            "description": "One of: `hour`, `day`, `month`, `unit`, `service`, `tax`, `other`, `product`, `article`."
          },
          "tax": {
            "$ref": "#/components/schemas/V3ItemTax"
          },
          "retention": {
            "type": "number",
            "example": 2
          }
        }
      },
      "V3ItemWritableFields": {
        "type": "object",
        "description": "Item fields accepted on create and update. Any other key inside `item` is ignored.",
        "properties": {
          "code": {
            "type": "string",
            "example": "Item name",
            "maxLength": 60,
            "description": "Item name/code. Values longer than 60 characters are rejected with HTTP 422 (`Code for the item is too long (maximum should be 60 characters)`) — they are not truncated. On update, it cannot be changed once the item is used in a non-draft document (HTTP 422 `Code can't be changed because it is already associated with invoices`)."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "example": "Item description",
            "maxLength": 200,
            "description": "Values longer than 200 characters are rejected with HTTP 422 (`Description is too long (maximum is 200 characters)`) — they are not truncated."
          },
          "unit_price": {
            "type": "number",
            "minimum": 0,
            "example": 9.99,
            "description": "A missing or non-numeric value is rejected with HTTP 422 (`Price is not valid. Check the decimal mark and if you are inserting only numbers.`)."
          },
          "rrp": {
            "type": "number",
            "minimum": 0,
            "example": 12.29,
            "description": "Recommended retail price. On create, when omitted, it is computed as `unit_price` plus the item's tax. On update, an omitted value is left unchanged."
          },
          "unit": {
            "type": "string",
            "example": "service",
            "description": "One of: `hour`, `day`, `month`, `unit`, `service`, `tax`, `other`, `product`, `article`. On create, defaults to `service` when omitted; on update, an omitted unit is left unchanged."
          },
          "tax": {
            "type": "object",
            "description": "Tax of the item, by name. When omitted, create uses the account's default tax and update keeps the current tax.\nAn unknown name is rejected on create with HTTP 422 (`Tax must exist`); on update it is ignored and the current tax is kept.",
            "properties": {
              "name": {
                "type": "string",
                "example": "IVA23"
              }
            }
          },
          "retention": {
            "type": "number",
            "example": 2,
            "description": "Retention rate (%). Defaults to `0` when omitted."
          }
        }
      },
      "V3ItemDetailObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "code": {
            "type": "string",
            "example": "Item name",
            "maxLength": 60
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "example": "Item description",
            "maxLength": 200
          },
          "unit_price": {
            "type": "number",
            "example": 9.99
          },
          "rrp": {
            "type": "number",
            "example": 12.29
          },
          "unit": {
            "type": "string",
            "example": "service",
            "description": "One of: `hour`, `day`, `month`, `unit`, `service`, `tax`, `other`, `product`, `article`."
          },
          "unit_sold": {
            "type": "number",
            "example": 16
          },
          "total_sold": {
            "type": "number",
            "example": 196.8
          },
          "total_sold_before_taxes": {
            "type": "number",
            "example": 160
          },
          "currency": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "example": "EUR"
              },
              "symbol": {
                "type": "string",
                "example": "€"
              }
            }
          },
          "tax": {
            "$ref": "#/components/schemas/V3ItemTax"
          },
          "retention": {
            "type": "number",
            "example": 2
          }
        }
      },
      "V3ScheduleListItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "client_name": {
            "type": "string",
            "example": "John Doe"
          },
          "interval": {
            "type": "integer",
            "example": 1
          },
          "type": {
            "type": "string",
            "enum": [
              "Daily",
              "Monthly",
              "Yearly"
            ],
            "example": "Monthly"
          },
          "description": {
            "type": "string",
            "example": "Monthly invoice",
            "maxLength": 255
          },
          "active": {
            "type": "boolean",
            "example": true
          },
          "document_type": {
            "type": "string",
            "enum": [
              "invoice",
              "invoice_receipt",
              "simplified_invoice"
            ],
            "example": "invoice"
          },
          "to_send": {
            "type": "boolean",
            "example": false
          },
          "email_cc": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "email_bcc": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "start_date": {
            "type": "string",
            "format": "date",
            "example": "2026-08-01"
          },
          "next_date": {
            "type": "string",
            "format": "date",
            "example": "2020-01-01"
          },
          "end_date": {
            "type": "string",
            "format": "date",
            "example": "2030-01-01"
          },
          "total": {
            "type": "integer",
            "description": "Occurrences the schedule is planned to produce over its whole date range (a forecast, not a document count)",
            "example": 2
          },
          "total_remain": {
            "type": "integer",
            "description": "Occurrences still to come between now and `end_date`",
            "example": 2
          }
        }
      },
      "V3ScheduleTemplate": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "example": "2025-10-20"
          },
          "due_date": {
            "type": "string",
            "format": "date",
            "example": "2025-10-20"
          },
          "client": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "example": "John Doe"
              }
            }
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "example": "Item 1"
                },
                "quantity": {
                  "type": "integer",
                  "example": 1
                },
                "unit_price": {
                  "type": "number",
                  "example": 10
                },
                "tax": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "example": "IVA23"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "V3ScheduleGeneratedDocument": {
        "type": "object",
        "description": "The draft document generated from the schedule's template.",
        "properties": {
          "id": {
            "type": "integer",
            "example": 264626040
          },
          "status": {
            "type": "string",
            "example": "draft"
          },
          "archived": {
            "type": "boolean",
            "example": false
          },
          "type": {
            "type": "string",
            "example": "Template"
          },
          "sequence_number": {
            "type": "string",
            "example": "draft"
          },
          "inverted_sequence_number": {
            "type": "string",
            "example": "draft"
          },
          "sequence_id": {
            "type": [
              "integer",
              "null"
            ],
            "example": null
          },
          "atcud": {
            "type": "string",
            "example": "N/A"
          },
          "date": {
            "type": "string",
            "format": "date",
            "example": "2026-08-01"
          },
          "due_date": {
            "type": "string",
            "format": "date",
            "example": "2026-08-15"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "observations": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "token": {
            "type": "string",
            "example": "2646260403677fd1d1a71ef33e06d27d39dbb11664aaafad8"
          },
          "permalink": {
            "type": "string",
            "example": "https://web.invoicexpress.com/documents/2646260403677fd1d1a71ef33e06d27d39dbb11664aaafad8?language=pt"
          },
          "retention": {
            "type": "number",
            "example": 0
          },
          "global_discount": {
            "type": [
              "number",
              "null"
            ],
            "example": null
          },
          "account": {
            "type": "object",
            "properties": {
              "organization_name": {
                "type": "string",
                "example": "invoicexpress"
              },
              "address": {
                "type": "object",
                "properties": {
                  "detail": {
                    "type": "string",
                    "example": "Avenida Duque D'Avila, Saldanha"
                  },
                  "postal_code": {
                    "type": "string",
                    "example": "1500-555"
                  },
                  "city": {
                    "type": "string",
                    "example": "Lisbon"
                  },
                  "country": {
                    "type": "string",
                    "example": "Portugal"
                  }
                }
              },
              "email": {
                "type": "string",
                "example": "tito.reis@visma.com"
              },
              "fiscal_id": {
                "type": "string",
                "example": "999999990"
              },
              "logo": {
                "type": "string",
                "example": ""
              },
              "bank_data": {
                "type": "array",
                "items": {
                  "type": "object"
                },
                "example": []
              }
            }
          },
          "client": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "example": 194666511
              },
              "name": {
                "type": "string",
                "example": "Test Client"
              },
              "email": {
                "type": "string",
                "example": ""
              },
              "fiscal_id": {
                "type": "string",
                "example": ""
              },
              "country": {
                "type": "string",
                "example": ""
              },
              "address": {
                "type": "object",
                "properties": {
                  "detail": {
                    "type": "string",
                    "example": ""
                  },
                  "postal_code": {
                    "type": "string",
                    "example": ""
                  },
                  "city": {
                    "type": "string",
                    "example": ""
                  },
                  "address_country": {
                    "type": "string",
                    "example": "PT"
                  }
                }
              }
            }
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 484043788
                },
                "name": {
                  "type": "string",
                  "example": "Test Item"
                },
                "description": {
                  "type": "string",
                  "example": ""
                },
                "unit_price": {
                  "type": "number",
                  "example": 10
                },
                "unit": {
                  "type": "string",
                  "example": "service"
                },
                "quantity": {
                  "type": "number",
                  "example": 1
                },
                "tax": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "example": 756700
                    },
                    "name": {
                      "type": "string",
                      "example": "IVA23"
                    },
                    "value": {
                      "type": "number",
                      "example": 23
                    }
                  }
                },
                "discount": {
                  "type": "number",
                  "example": 0
                },
                "subtotal": {
                  "type": "number",
                  "example": 10
                },
                "tax_amount": {
                  "type": "number",
                  "example": 2.3
                },
                "discount_amount": {
                  "type": "number",
                  "example": 0
                },
                "total": {
                  "type": "number",
                  "example": 12.3
                },
                "retention": {
                  "type": "number",
                  "example": 0
                }
              }
            }
          },
          "summary": {
            "type": "object",
            "properties": {
              "sum": {
                "type": "number",
                "example": 10
              },
              "discount": {
                "type": "number",
                "example": 0
              },
              "before_taxes": {
                "type": "number",
                "example": 10
              },
              "taxes": {
                "type": "number",
                "example": 2.3
              },
              "total": {
                "type": "number",
                "example": 12.3
              },
              "currency": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Euro"
                  },
                  "code": {
                    "type": "string",
                    "example": "EUR"
                  },
                  "symbol": {
                    "type": "string",
                    "example": "€"
                  }
                }
              },
              "retention": {
                "type": "number",
                "example": 0
              },
              "pay_progress": {
                "type": "number",
                "example": 0
              },
              "to_pay": {
                "type": "number",
                "example": 12.3
              },
              "total_paid": {
                "type": "number",
                "example": 0
              },
              "taxes_breakdown": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "category": {
                      "type": "string",
                      "example": "IVA23"
                    },
                    "items_value": {
                      "type": "number",
                      "example": 10
                    },
                    "tax_value": {
                      "type": "number",
                      "example": 2.3
                    }
                  }
                }
              },
              "total_currency_rate": {
                "type": "number",
                "example": 0
              },
              "rate": {
                "type": "number",
                "example": 1
              }
            }
          },
          "owner_invoice_id": {
            "type": [
              "integer",
              "null"
            ],
            "example": null
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "auto_add_related_document": {
            "type": "boolean",
            "example": false
          }
        }
      },
      "V3ScheduleObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "client_name": {
            "type": "string",
            "example": "John Doe"
          },
          "interval": {
            "type": "integer",
            "example": 1
          },
          "type": {
            "type": "string",
            "enum": [
              "Daily",
              "Monthly",
              "Yearly"
            ],
            "example": "Monthly"
          },
          "description": {
            "type": "string",
            "example": "Monthly invoice",
            "maxLength": 255
          },
          "active": {
            "type": "boolean",
            "example": true
          },
          "document_type": {
            "type": "string",
            "enum": [
              "invoice",
              "invoice_receipt",
              "simplified_invoice"
            ],
            "example": "invoice"
          },
          "to_send": {
            "type": "boolean",
            "example": false
          },
          "email_cc": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255
          },
          "email_bcc": {
            "type": [
              "string",
              "null"
            ],
            "example": null,
            "maxLength": 255
          },
          "start_date": {
            "type": "string",
            "format": "date",
            "example": "2026-08-01"
          },
          "next_date": {
            "type": "string",
            "format": "date",
            "example": "2020-01-01"
          },
          "end_date": {
            "type": "string",
            "format": "date",
            "example": "2030-01-01"
          },
          "total": {
            "type": "integer",
            "description": "Occurrences the schedule is planned to produce over its whole date range (a forecast, not a document count)",
            "example": 2
          },
          "issued": {
            "type": "integer",
            "description": "Documents actually generated so far by this schedule (deleted ones excluded). Not equal to `total - total_remain`. Not returned in the list.",
            "example": 0
          },
          "total_remain": {
            "type": "integer",
            "description": "Occurrences still to come between now and `end_date`",
            "example": 2
          },
          "template": {
            "$ref": "#/components/schemas/V3ScheduleGeneratedDocument"
          }
        }
      },
      "V3ScheduleTimelineItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 648557688
          },
          "type": {
            "type": "string",
            "example": "Activity"
          },
          "event": {
            "type": "string",
            "example": "Created",
            "description": "Human-readable, translated label of the event (e.g. `Created`, `Finalized`, `Comment`), not a stable key. Do not branch on it; use `type` instead."
          },
          "author": {
            "type": "string",
            "example": "user@invoicexpress.com"
          },
          "message": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "author": {
                    "type": "string",
                    "example": "user@invoicexpress.com"
                  }
                }
              }
            }
          },
          "to": {
            "type": [
              "string",
              "null"
            ],
            "example": null
          },
          "date": {
            "type": "string",
            "format": "date-time",
            "example": "2026-07-27T11:57:03+01:00"
          },
          "can_change": {
            "type": "boolean",
            "example": false
          },
          "time_to_change": {
            "type": "integer",
            "example": 0
          }
        }
      },
      "V3TaxObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "name": {
            "type": "string",
            "example": "IVA23",
            "maxLength": 255
          },
          "value": {
            "type": "number",
            "example": 23
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "example": "NOR",
            "maxLength": 255,
            "description": "Tax code. Not validated server-side and stored as sent; `null` when not set."
          },
          "region": {
            "type": [
              "string",
              "null"
            ],
            "example": "PT",
            "description": "Tax region. An ISO-3166 alpha-2 country code, plus the Portuguese autonomous regions `PT-AC` (Azores) and `PT-MA` (Madeira). May be `null` (the tax named `Isento` does not require a region)."
          },
          "default_tax": {
            "type": "integer",
            "example": 1
          }
        }
      },
      "V3TaxWritableFields": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "IVA23",
            "maxLength": 255,
            "description": "Must be unique among the account's taxes."
          },
          "value": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "example": 23,
            "description": "Percentage, from 0 to 100."
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "example": "NOR",
            "maxLength": 255,
            "description": "Tax code. Not validated server-side and stored as sent; `null` when not set."
          },
          "region": {
            "type": "string",
            "example": "PT",
            "description": "Tax region. An ISO-3166 alpha-2 country code, plus the Portuguese autonomous regions `PT-AC` (Azores) and `PT-MA` (Madeira). Required, and checked against that list, unless `name` is `Isento`."
          },
          "default_tax": {
            "type": "integer",
            "example": 1,
            "description": "`1` makes this tax the account's default tax. Any other value (including `0`) changes nothing: it does not unset the current default."
          }
        }
      },
      "V3UserObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "name": {
            "type": "string",
            "example": "Jean Dias",
            "description": "No enforced character limit (text column)."
          },
          "email": {
            "type": "string",
            "example": "john.doe@invoicexpress.com",
            "maxLength": 255
          },
          "phone": {
            "type": "string",
            "example": "987654321",
            "description": "No enforced character limit (text column)."
          },
          "phone_country_id": {
            "type": "integer",
            "example": 1
          },
          "accepted_marketing": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "V3UserAccountObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "name": {
            "type": "string",
            "example": "companyname"
          },
          "organization_name": {
            "type": "string",
            "example": "Company Name"
          },
          "fiscal_id": {
            "type": [
              "string",
              "null"
            ],
            "example": "123456789"
          },
          "email": {
            "type": "string",
            "example": "john.doe@example.com"
          }
        }
      },
      "V3CurrencyObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "name": {
            "type": "string",
            "example": "Euro"
          },
          "symbol": {
            "type": "string",
            "example": "€"
          },
          "code": {
            "type": "string",
            "description": "ISO 4217 currency code",
            "example": "EUR"
          },
          "prefered": {
            "type": "integer",
            "description": "Sort order used to rank preferred currencies first",
            "example": 1
          }
        }
      },
      "V3FavoriteFilters": {
        "type": "object",
        "description": "Opaque client-side state. The API stores the object as sent and returns it unchanged; it does not validate or interpret any key. The keys below are the ones the web app uses.",
        "additionalProperties": true,
        "properties": {
          "page": {
            "type": "integer",
            "example": 1
          },
          "itemsPerPage": {
            "type": "string",
            "example": "10"
          },
          "showTotalWithIVA": {
            "type": "boolean",
            "example": false
          },
          "text": {
            "type": "string",
            "example": ""
          },
          "type": {
            "type": "object",
            "properties": {
              "invoice": {
                "type": "boolean",
                "example": true
              },
              "invoiceReceipt": {
                "type": "boolean",
                "example": true
              },
              "simplifiedInvoice": {
                "type": "boolean",
                "example": true
              },
              "cashInvoice": {
                "type": "boolean",
                "example": true
              },
              "debitNote": {
                "type": "boolean",
                "example": true
              },
              "vatMossInvoice": {
                "type": "boolean",
                "example": true
              },
              "creditNote": {
                "type": "boolean",
                "example": true
              },
              "vatMossCreditNote": {
                "type": "boolean",
                "example": true
              },
              "receipt": {
                "type": "boolean",
                "example": true
              },
              "vatMossReceipt": {
                "type": "boolean",
                "example": true
              }
            }
          },
          "status": {
            "type": "object",
            "properties": {
              "draft": {
                "type": "boolean",
                "example": true
              },
              "sent": {
                "type": "boolean",
                "example": true
              },
              "settled": {
                "type": "boolean",
                "example": true
              },
              "canceled": {
                "type": "boolean",
                "example": true
              },
              "second_copy": {
                "type": "boolean",
                "example": true
              }
            }
          },
          "archived": {
            "type": "boolean",
            "example": false
          },
          "nonArchived": {
            "type": "boolean",
            "example": true
          },
          "documentTotalRange": {
            "type": "object",
            "properties": {
              "from": {
                "type": [
                  "string",
                  "null"
                ],
                "example": ""
              },
              "to": {
                "type": [
                  "string",
                  "null"
                ],
                "example": ""
              }
            }
          },
          "sort": {
            "type": "string",
            "example": "document_date"
          },
          "sortOrder": {
            "type": "string",
            "example": "desc"
          },
          "series": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": []
          },
          "plugins": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": []
          },
          "clientList": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": []
          },
          "batchId": {
            "type": "string",
            "example": ""
          },
          "registration": {
            "type": "object",
            "properties": {
              "registered": {
                "type": "boolean",
                "example": true
              },
              "notRegistered": {
                "type": "boolean",
                "example": true
              },
              "partiallyRegistered": {
                "type": "boolean",
                "example": true
              }
            }
          },
          "issueDate": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string",
                "example": ""
              },
              "to": {
                "type": "string",
                "example": ""
              }
            }
          },
          "issueDateLabel": {
            "type": "string",
            "example": ""
          },
          "dueDate": {
            "type": "object",
            "properties": {
              "from": {
                "type": "string",
                "example": ""
              },
              "to": {
                "type": "string",
                "example": ""
              }
            }
          },
          "dueDateLabel": {
            "type": "string",
            "example": ""
          }
        }
      },
      "V3FavoriteSummaryObject": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "favorite_overdue_invoices"
          },
          "uid": {
            "type": "string",
            "example": "Default_4"
          }
        }
      },
      "V3PaymentServiceCredential": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "ApiKey"
          },
          "key": {
            "type": "string",
            "example": "api_key"
          },
          "value": {
            "type": "string",
            "example": "1234-5678-9123-4567"
          },
          "type": {
            "type": "string",
            "example": "text"
          },
          "editable": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "V3PaymentServiceExtraOptions": {
        "type": "object",
        "properties": {
          "auto_add_payment_reference": {
            "type": "boolean",
            "example": true
          },
          "auto_add_payment_reference_estimates": {
            "type": "boolean",
            "example": false
          },
          "auto_send_invoice_from_estimate": {
            "type": "boolean",
            "example": false
          }
        }
      },
      "V3PaymentServiceObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "name": {
            "type": "string",
            "example": "euPago"
          },
          "url": {
            "type": "string",
            "example": "https://eupago.pt"
          },
          "logo": {
            "type": "string",
            "description": "An HTML `<img>` tag, not a URL.",
            "example": "<img src='/ix_images/gateway_eupago.png' alt='euPago' height='70'>"
          },
          "configured": {
            "type": "boolean",
            "example": true
          },
          "credentials": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/V3PaymentServiceCredential"
            }
          },
          "extra_options": {
            "description": "The account's payment options. An empty object `{}` unless this is the configured payment service.",
            "allOf": [
              {
                "$ref": "#/components/schemas/V3PaymentServiceExtraOptions"
              }
            ]
          }
        }
      },
      "V3PaymentServiceReferenceObject": {
        "type": "object",
        "properties": {
          "mb_reference": {
            "type": "object",
            "properties": {
              "entity": {
                "type": "string",
                "example": "20123"
              },
              "reference": {
                "type": "string",
                "example": "123456789"
              },
              "value": {
                "type": "string",
                "example": "10.0"
              },
              "date": {
                "type": "string",
                "example": "2024-12-19 16:52:48 +0000"
              }
            }
          },
          "document": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "example": "invoices/1234"
              },
              "status": {
                "type": "string",
                "example": "settled"
              },
              "sequence": {
                "type": "string",
                "example": "Company/1"
              }
            }
          }
        }
      },
      "V3PhoneCallingCodeObject": {
        "type": "object",
        "properties": {
          "phone_country_id": {
            "type": "integer",
            "example": 1
          },
          "phone_code": {
            "type": "string",
            "description": "Label with the country name in English.",
            "example": "Portugal (+351)"
          },
          "translated_phone_code": {
            "type": "string",
            "description": "Same label with the country name translated to the response language (see the `language` query parameter). Unknown names are kept in English.",
            "example": "Portugal (+351)"
          },
          "code": {
            "type": "number",
            "example": 351
          }
        }
      },
      "V3BalancePerClientObject": {
        "type": "object",
        "properties": {
          "client_id": {
            "type": "integer",
            "example": 123
          },
          "client_name": {
            "type": "string",
            "example": "John Doe"
          },
          "client_fiscal_id": {
            "type": [
              "string",
              "null"
            ],
            "example": "508025338"
          },
          "total": {
            "type": "number",
            "example": 100
          },
          "total_paid": {
            "type": "number",
            "example": 80
          },
          "balance": {
            "type": "number",
            "example": 20
          }
        }
      },
      "V3ReportsPagination": {
        "type": "object",
        "properties": {
          "current_page": {
            "type": "integer",
            "example": 1
          },
          "total_pages": {
            "type": "integer",
            "example": 10
          },
          "total_count": {
            "type": "integer",
            "example": 100
          },
          "per_page": {
            "type": "integer",
            "example": 10
          }
        }
      },
      "V3BalancePerClientTotals": {
        "type": "object",
        "properties": {
          "total": {
            "type": "number",
            "example": 100
          },
          "total_paid": {
            "type": "number",
            "example": 80
          },
          "balance": {
            "type": "number",
            "example": 20
          }
        }
      },
      "V3BalancePerClientSummaryObject": {
        "type": "object",
        "properties": {
          "total": {
            "type": "number",
            "example": 100
          },
          "total_paid": {
            "type": "number",
            "example": 80
          },
          "balance": {
            "type": "number",
            "example": 20
          }
        }
      },
      "V3TaxCountryObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1
          },
          "name": {
            "type": "string",
            "description": "Country name in English. Kept untranslated because it is used as a lookup key.",
            "example": "Portugal"
          },
          "translated_name": {
            "type": "string",
            "description": "Country name translated to the response language (see the `language` query parameter).",
            "example": "Portugal"
          },
          "country_code": {
            "type": "string",
            "example": "PT"
          },
          "tax_location_id": {
            "type": "integer",
            "example": 1
          }
        }
      },
      "V3DigitalSignatureInfoObject": {
        "type": "object",
        "properties": {
          "uid": {
            "type": "string",
            "description": "Account ID used as the unique identifier",
            "example": "12345"
          },
          "accessToken": {
            "type": "string",
            "description": "Encrypted access token for the digital signature provider",
            "example": "encrypted_access_token_here"
          },
          "credentialId": {
            "type": "string",
            "description": "Unique credential identifier from the digital signature provider",
            "example": "PRT.123456789-PRT.123 123 123-abc123-ab12-cd34-ef56-123456789abc"
          },
          "clientSecret": {
            "type": "string",
            "description": "Client secret for authentication with the digital signature provider",
            "example": "weWihPC67jwTdtAVx2UR@"
          },
          "expiration_date": {
            "type": "string",
            "format": "date",
            "description": "Expiration date of the digital signature credentials",
            "example": "2024-12-31"
          },
          "provider": {
            "type": "string",
            "description": "Name of the digital signature provider",
            "enum": [
              "multicert",
              "ama"
            ],
            "example": "multicert"
          },
          "is_online_signature": {
            "type": "boolean",
            "description": "Indicates if the signature is performed online",
            "example": true
          },
          "refreshToken": {
            "type": "string",
            "description": "Encrypted refresh token for renewing access",
            "example": "encrypted_refresh_token_here"
          },
          "fiscalId": {
            "type": "string",
            "description": "Fiscal ID associated with the digital signature",
            "example": "123456789"
          },
          "status": {
            "type": "string",
            "description": "Current status of the digital signature configuration. Observed values include numeric-string codes (e.g. \"2\") as well as the named states ACTIVE, IN_PROGRESS, EXPIRED, CANCELLED — treat as an opaque string rather than a fixed enum.",
            "example": "2"
          },
          "is_status_communicated": {
            "type": "boolean",
            "description": "Indicates if the status has been communicated to external systems",
            "example": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the digital signature configuration was created",
            "example": "2024-01-15T10:30:00Z"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the digital signature configuration was last updated",
            "example": "2024-01-15T10:30:00Z"
          }
        }
      }
    }
  }
}